ImageComparison
Compares aligned before and after media with an accessible reveal control.
See it and copy it
Framework example
Choose Astro, React, or Elements to compare native usage against the shared visual output. Each example assumes the framework-level setup is already complete.
Illustrative color treatment. Move the control to compare the same framing.
View ImageComparison code
Framework usage
Switch targets to compare the adapter code. This live preview runs the Astro example. React and Elements use their own behavior APIs; complete the matching framework setup before copying an example.---
import { Image, ImageComparison } from '@santi020k/lumen-astro'
---
<ImageComparison afterLabel="Color adjusted" beforeLabel="Original" label="Compare the landscape treatment" ratio={1.6} value={50}>
<Image slot="before" alt="A muted landscape illustration with mountains and a lake" height={600} radius="none" src="/comparison-before.svg" width={960} />
<Image slot="after" alt="The same landscape illustration with warmer light and deeper color" height={600} radius="none" src="/comparison-after.svg" width={960} />
<p>Illustrative color treatment. Move the control to compare the same framing.</p>
</ImageComparison>import { Image, ImageComparison } from '@santi020k/lumen-react'
export const Example = () => (
<ImageComparison
label="Compare the landscape treatment"
beforeLabel="Original"
afterLabel="Color adjusted"
ratio={1.6}
defaultValue={50}
before={<Image alt="Original landscape illustration" src="/comparison-before.svg" />}
after={<Image alt="Color-adjusted landscape illustration" src="/comparison-after.svg" />}
/>
)<script type="module">
import { defineLumenElements } from '@santi020k/lumen-elements/define'
defineLumenElements()
</script>
<lumen-image-comparison
label="Compare the landscape treatment"
before-label="Original"
after-label="Color adjusted"
ratio="1.6"
value="50"
>
<img slot="before" alt="Original landscape illustration" src="/comparison-before.svg" width="960" height="600" />
<img slot="after" alt="Color-adjusted landscape illustration" src="/comparison-after.svg" width="960" height="600" />
<p>Illustrative color treatment with matching framing.</p>
</lumen-image-comparison>Choose your target
Add this component
Choose the package for your runtime. All adapters share the Lumen stylesheet. Use the matching registry command when you want a local wrapper for that framework.
pnpm add @santi020k/lumen-astropnpm add @santi020k/lumen-astrolumen add ImageComparisonlumen add ImageComparisonpnpm add @santi020k/lumen-reactpnpm add @santi020k/lumen-reactlumen add ImageComparison --target reactlumen add ImageComparison --target reactpnpm add @santi020k/lumen-elementspnpm add @santi020k/lumen-elementslumen add ImageComparison --target elementslumen add ImageComparison --target elementsAPI reference
Lumen-specific props and runtime attributes for the Astro primitive. Use the framework differences above and the copyable examples for React composition and Elements attributes; the public adapter types define their supported contracts.
| Attribute | Values | Default | Description |
|---|---|---|---|
| label | string | required | Provides the visible label for the native comparison range control. |
| before / after | named Astro slots | ReactNode props | slotted child nodes | required | Supplies media with matching framing and meaningful alternative text. Media is clipped, never resized as the range moves. |
| beforeLabel / afterLabel | string | "Before" / "After" | Labels each side. Elements uses before-label and after-label attributes. |
| value / defaultValue | number | 50 | Percentage of the after image revealed (0–100). React value is controlled; defaultValue initializes local state. Astro value is the initial position; Elements value is reflected. |
| onValueChange | (value: number) => void | - | React callback for user changes. Astro and Elements emit ui:image-comparison-change with { value }. |
| ratio | number | 16 / 9 | Sets a shared positive finite aspect ratio. Invalid values fall back to 16 / 9. |
| fit | "cover" | "contain" | "cover" | Applies the same media fit to both layers. |
| disabled | boolean | false | Disables the native range without hiding either image. Astro keeps the range disabled until UIPrimitives enhances the static comparison. |
| locale | string | environment locale | Formats the accessible percentage. Localize label, beforeLabel, and afterLabel separately. |
| mode | "reveal" | "side-by-side" | "before" | "after" | "reveal" | Changes the view without replacing media or resetting the reveal. Alternate views hide and disable the range. Change data-mode in enhanced Astro, mode in Elements, or the React prop. |
| class, className | string | "" | Merges custom classes with the generated ui-* root classes. |
| ...native attributes | HTML attributes | - | Forwards standard attributes to the root element unless the component consumes them. |
Keyboard interactions
Keyboard behavior provided by the Astro UIPrimitives runtime for this component.
| Key | Action |
|---|---|
| Arrow keys | Adjust the reveal using the native range control; horizontal direction follows writing direction. |
| Home / End | Reveal the full before / after image. |
Runtime events
CustomEvents dispatched by the Astro UIPrimitives runtime for this component.
| Event | Target | Detail | When |
|---|---|---|---|
| ui:image-comparison-change | ImageComparison root | { value: number } | Fires as the native range changes the percentage of the after image revealed. |