Compare Slider

Anatomy

CompareSlider is the frame. CompareSliderBefore and CompareSliderAfter are two layers that both fill it (absolute inset-0) and are clipped at the divider — Before on the left, or on top when vertical. CompareSliderHandle draws the divider and is the slider itself; CompareSliderLabel is an optional corner chip. The value is a percentage: how much of the Before side is showing.

import {
  CompareSlider,
  CompareSliderAfter,
  CompareSliderBefore,
  CompareSliderHandle,
  CompareSliderLabel
} from '@comitor/ui'

<CompareSlider                       // the frame — has NO height of its own: give it aspect-* or h-*
  defaultValue={50}                  // or value + onValueChange — % of the BEFORE side showing
  className="aspect-[3/2] w-full"
>
  <CompareSliderBefore asChild>      // left (top when vertical)
    <img src={original} alt="…" />
  </CompareSliderBefore>
  <CompareSliderAfter asChild>       // right (bottom when vertical)
    <img src={edited} alt="…" />
  </CompareSliderAfter>
  <CompareSliderHandle />            // role="slider" — the ONLY keyboard stop. Never leave it out.
  <CompareSliderLabel side="before" />  // "Before" — default text from the compareSlider namespace
  <CompareSliderLabel side="after" />   // "After"
</CompareSlider>

Because both layers are absolutely positioned, the frame has no height of its own — without one it collapses to 0 and nothing shows. Give it an aspect-* class that matches the images, or a fixed h-*; either way the page does not jump when the images finish loading.

Basic usage

The usual shape: asChild on both layers, so each <img> is the layer — it receives object-cover, the full size and the clip. Drag the divider, or click anywhere on the picture: the divider jumps there, and focus moves to the handle so the arrow keys work straight after. On a phone, a vertical swipe across the picture still scrolls the page.

PreviewCode

Before

After

An <img> cannot hold children, so a layer rendered asChild ignores its label prop — in development the console says so. Put a separate <CompareSliderLabel side="before" /> and side="after" inside the frame instead; without children they show the default text for their side.

Labels on the layers

Without asChild a layer is a <div> that can carry its own label. label takes true for the default text of the language in use — “Before” and “After” in English — or a string of your own, here the revision being reviewed. Size the image inside yourself (size-full object-cover).

PreviewCode

Before

Retouched, v3

A labelled layer becomes role="group" named by its label, and the alt of the image inside is still read. The label is a solid chip — background and text from the theme, no transparency — so it reads the same over any picture.

Controlled position

value and onValueChange hold the position in your state — for presets, for keeping two comparisons in step, or for remembering where a reviewer left off. 0 shows only the edited image, 100 only the original. Use the buttons, then drag: the counter only moves for changes made in the slider — setting value from outside does not echo back through onValueChange.

PreviewCode

Edited onlyHalf and halfOriginal only50.0% original

value = 50.000 · onValueChange calls = 0

Pointer positions arrive unrounded — 37.2384… — so round before you store or display one. The handle announces it rounded to one decimal.

Keyboard and step

The handle is a single Tab stop. Horizontally the keys behave like a native <input type="range">: → ↑ PageUp increase the value (the divider moves right, showing more of the original), ← ↓ PageDown decrease it, Home goes to 0 and End to 100. step sets one arrow press; Shift + arrow, PageUp and PageDown move ten steps. Tab to the handle below (or click the picture) and try them — each arrow moves 5, with Shift 50.

PreviewCode

step = 5 · value = 50.0

Vertically the keys follow the arrow, not the number: ↑ ← PageUp move the divider up, ↓ → PageDown move it down. Since the value is measured from the top edge, ↑ decreases it there — the opposite of the ARIA slider pattern, where up always increases. The announced value text is the real number, so nothing is misreported.

Follow the pointer

interaction="hover" moves the divider with the pointer, no press needed — quick for scanning a picture with a mouse. The knob is hidden in this mode and appears only when the handle has keyboard focus, so a keyboard user still sees where they are. Touchscreens have no hover: there the divider only moves while a finger slides across the picture, so keep the default "drag" where people mostly use phones or tablets.

PreviewCode

Before

After

Vertical

orientation="vertical" puts Before on top and After below — the natural split for a sky or a horizon. The After label moves to the bottom-left corner. One sizing difference: the vertical root is h-full instead of w-full, so set the width yourself and add h-auto to let an aspect-* class size it (or use a fixed h-*). Here a sideways swipe on a phone scrolls; a vertical one moves the divider.

PreviewCode

Before

After

value = 50.0 (share of the top, Before, showing)

Restyling the handle

CompareSliderHandle is the only part that takes keyboard focus and the only one with role="slider". Leave it out and the comparison cannot be operated by keyboard or reached by a screen reader at all. To make it look different, pass children — the element keeps its role, name, value and keys, and gets a focus outline around the strip you draw.

PreviewCode

50%

Your drawing replaces the default’s visibility guarantee too. This one keeps it by reusing the same bg-paper + ring-ink pair; a single colour — bg-background, say — vanishes on some images.

A divider you can see on any image

Behind the divider is a photo, not the page, so no single colour is enough: white vanishes on a product cut out on white, near-black on a night shot. The divider is two-toned — a 2px paper core edged with ink — and so is the knob. Both tokens stay the same in every theme and contrast setting. Against any pixel at least one of the two reaches 4.21:1; the worst case is a mid grey like the middle stripe below.

PreviewCode

The focus ring follows the same idea: the brand-coloured outline sits between the paper knob and a 4px ink ring, so it shows even on an image in the brand’s own colour.

Language

Four strings live in the compareSlider namespace: the handle’s name, its value text, and the default Before and After labels. valueText is a function because the number sits inside it — Vietnamese writes a decimal comma, “37,5%”. The labels prop beats the nearest ComitorLocaleProvider, which beats English. Switch the language and read the handle back:

PreviewCode

EnglishTiếng Việt

Before

After

Handle in the DOM: aria-label “” · aria-valuetext “”

Image alt text is always yours, in the language of the page. Where the provider goes and how messages overrides work: Get started → Set the language. An app that builds a full message table of its own (a third language) must add the compareSlider namespace from 3.15.0, or typecheck fails.

Props

CompareSlider — every other prop goes to the frame’s <div>.

CompareSliderBefore and CompareSliderAfter — the same props; every other prop goes to the layer.

CompareSliderHandle — every other prop goes to the slider element.

CompareSliderLabel — every other prop goes to the chip’s <div>.

CompareSliderLabels — the compareSlider namespace, and the shape of the labels prop.

Known limitations

• No handle, no keyboard. Everything keyboard and screen reader users get lives on CompareSliderHandle. A comparison without it works only with a pointer.
• No height of its own. Forget the aspect-* or h-* and the frame is 0px tall. In vertical orientation the root is also h-full rather than w-full.
• Vertical ↑ decreases the value. The divider follows the arrow, but the ARIA slider pattern says up increases. The value text is the true number.
• No right-to-left mirroring. Before stays on the left and the arrow keys are not flipped under dir="rtl".
• asChild drops label. Use a separate CompareSliderLabel; development builds warn in the console.
• Controlled means echoed, not enforced. The slider moves before it calls onValueChange; a parent that ignores the call does not move it back. Passing a new value does.
• Not yet hand-tested everywhere. The package’s release notes list detailed drag and keyboard behaviour, screen readers, Safari and Firefox as not yet checked by hand for this component.

Accessibility

• CompareSliderHandle is role="slider" with tabIndex=0, aria-label (“Comparison position” by default), aria-valuemin 0, aria-valuemax 100, aria-valuenow rounded to one decimal, a localized aria-valuetext, and aria-orientation. Name it after the task when a page has several — “Compare retouch of photo 3”.
• The frame is a plain <div>: images keep their alt, and labelled layers are named groups. Write an alt for both images that says what differs.
• Keyboard: one Tab stop. Arrows move by step, Shift + arrow and PageUp/PageDown by ten steps, Home/End to 0 and 100. Horizontal matches a native range input; vertical follows the arrow.
• A pointer press moves focus to the handle, like a native range input, so the keys work straight after a click.
• The default knob is 44px (size-11), and the handle strip is 40px wide across the full height of the frame — above the 24px target size of WCAG 2.5.8.
• The divider, knob and focus ring are two-toned so they stay visible on any image (at least 4.21:1 against one of the two tones); labels are solid chips in theme colours.

Related

• Cropper — the other image tool; its crop frame uses the same paper and ink pair.
• Upload — getting the original and the edited file into the app.
• Slider — a plain range input, for values that are not a comparison.
• Aspect Ratio — another way to give the frame its height.