Range Slider
A two-thumb slider built on two native <input type="range"> elements sharing
one track — each thumb keeps the browser’s own slider role, keyboard control,
pointer drag and form participation.
A separate component from Slider, not a mode on it: the value is a pair, and every operation (the clamp, the dependent bound, reporting) works on the pair as a whole.
Import
Section titled “Import”<script> import RangeSlider from "@invisible-ui/svelte/RangeSlider.svelte";</script><script setup> import { RangeSlider } from "@invisible-ui/vue";</script>import { RangeSlider } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-range-slider></ds-range-slider>In Elements, value holds the pair as lower,upper, and lower-label and
upper-label name the thumbs. Moving a thumb sends a bubbling change event
with the complete pair in detail.value:
<ds-range-slider label="Price" lower-label="Minimum price" upper-label="Maximum price" name="price" value="20,80"></ds-range-slider>| Prop | Type | Default | Description |
|---|---|---|---|
value | readonly [number, number] | [0, 100] | |
min | number | 0 | |
max | number | 100 | |
step | number | 1 | |
minDistance | number | 0 | The gap the two thumbs may not close. They may touch; they never cross. |
orientation | "horizontal" | "vertical" | "horizontal" | |
disabled | boolean | false | |
label * | string | — | Accessible name for the group. |
thumbLabels * | readonly [string, string] | — | Accessible name for each thumb: [lowerLabel, upperLabel]. |
error | string | undefined | undefined | Error message, shown under the track and announced. Both inputs point at it through aria-describedby and take aria-invalid. The app owns it: a form reset leaves it in place, so the app clears it. |
name | string | undefined | undefined | Form field name — both thumbs submit under it, in order: FormData.getAll(name) reads [String(lower), String(upper)]. |
showValue | boolean | false | Show the current values to the side of the track. |
showRange | boolean | false | Show the min and max reference values under the ends of the track. |
ticks | boolean | false | Show tick marks at each step (only when the count is reasonable). |
format | (value: number) => string | (v) => String(v) | Format a displayed value (e.g. add a unit). |
onValueChange | ((value: readonly [number, number]) => void) | undefined | undefined | Called with the complete pair whenever it changes. |
icon | Snippet | undefined | undefined | A decorative icon before the track. |
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | readonly [number, number] | undefined | v-model value; takes precedence over value when bound. |
value | readonly [number, number] | () => [0, 100] | |
min | number | 0 | |
max | number | 100 | |
step | number | 1 | |
minDistance | number | 0 | The gap the two thumbs may not close. They may touch; they never cross. |
orientation | RangeSliderOrientation | "horizontal" | |
disabled | boolean | false | |
label * | string | — | Accessible name for the group (required). |
thumbLabels * | readonly [string, string] | — | Accessible name for each thumb: [lowerLabel, upperLabel]. |
name | string | undefined | Form field name — both thumbs submit under it, in order: FormData.getAll(name) reads [String(lower), String(upper)]. |
showValue | boolean | false | Show the current values to the side of the track. |
showRange | boolean | false | Show the min and max reference values under the ends of the track. |
ticks | boolean | false | Show tick marks at each step (only when the count is reasonable). |
format | (value: number) => string | (value: number) => String(value) | Format a displayed value (e.g. add a unit). |
error | string | undefined | Error message. When non-empty it shows after the control as an alert and describes the control. The application owns it: a form reset leaves it in place, and the application clears it. |
onValueChange | (value: readonly [number, number]) => void | undefined | Called with the complete pair whenever it changes. |
| Event | Payload |
|---|---|
update:modelValue | value: readonly [number, number] |
Slots: icon.
| Prop | Type | Default | Description |
|---|---|---|---|
value | RangeValue | — | Initial (uncontrolled) or current (controlled) value. |
min | number | 0 | |
max | number | 100 | |
step | number | 1 | |
minDistance | number | 0 | The gap the two thumbs may not close. They may touch; they never cross. |
orientation | RangeSliderOrientation | "horizontal" | |
disabled | boolean | false | |
error | string | — | An error message shown under the control as an alert. It describes the control and marks it invalid. The app owns it: a form reset leaves it in place, so the app clears it. |
label * | string | — | Accessible name for the group (required). |
thumbLabels * | readonly [string, string] | — | Accessible name for each thumb: [lowerLabel, upperLabel]. |
name | string | — | Form field name. Both thumbs submit under it, in order: FormData.getAll(name) reads [String(lower), String(upper)]. |
showValue | boolean | false | Show the current values to the side of the track. |
showRange | boolean | false | Show the min and max reference values under the ends of the track. |
ticks | boolean | false | Show tick marks at each step (only when the count is reasonable). |
format | (value: number) => string | String | Format a displayed value (e.g. add a unit). |
onValueChange | (value: RangeValue) => void | — | Called with the complete pair whenever it changes. |
icon | ReactNode | — | A decorative icon before the track. |
| Attribute | Reactive | Description |
|---|---|---|
label * | yes | the group's accessible name |
value | yes | the pair as lower,upper; the whole range by default |
min | yes | 0 by default |
max | yes | 100 by default |
step | yes | 1 by default |
min-distance | yes | the gap the thumbs may not close; 0 by default |
orientation | yes | horizontal|vertical |
disabled | yes | |
name | yes | |
show-value | yes | |
show-range | yes | |
ticks | yes | |
error | yes | a message under the track that also marks both thumbs invalid; the page owns it, so a form reset leaves it in place |
Reactive attributes re-render the element when they change after the first render.
Properties: value ([lower, upper]), format ((value: number) => string).
Emits: bubbling change CustomEvent with detail.value, the complete pair, whenever the user moves a thumb.
Behaviour
Section titled “Behaviour”- The thumbs never cross. Dragging one past the other clamps it at the
other’s value (minus
minDistance, when given) instead of swapping which thumb is which. DOM order, tab order and thumb identity never change, even when both values are equal. - One action reports the complete pair, once.
onValueChangereceives[lower, upper]; reflecting a controlledvalueprop back reports nothing, and neither does a native form reset. minDistancerounds up to the step grid and is capped at the span. A distance the grid cannot express is taken as the next reachable one, never a smaller one, so the pair is never closer than was asked; a distance wider than the track leaves exactly one legal pair,[min, max]. A clamped value always lands on a value the user could have reached themselves.- Constraints may change after mount.
min,max,step,minDistance,orientationanddisabledreach the control without a remount. A pair the new constraints no longer allow is normalized silently, and the form-reset default with it; nothing is reported. - Pointer presses reach the nearer thumb, along the logical axis. Two overlapping range inputs hit-test by stacking order, so the thumb nearer the pointer is raised before the press lands, in horizontal LTR, horizontal RTL and vertical alike. A drag already in progress is never interrupted.
- Stacked thumbs stay operable without a hover. When both thumbs sit on
the same value, a pointer to one side of the stack reaches the thumb that
would move that way. With no pointer over the track at all, as with a touch,
the upper thumb is on top unless the pair is stacked at
max, where only the lower one can move; the other thumb is reached by moving the top one off it first.
Error message
Section titled “Error message”A non-empty error shows the message under the control with a hazard icon and
announces it as an alert. Both inputs point at it through aria-describedby and
take aria-invalid="true". The group around them takes neither. The message is
plain text.
<RangeSlider label="Ticket price" thumbLabels={["Lowest ticket price", "Highest ticket price"]} bind:value={ticketPrice} error={ticketPrice[1] > 80 ? "The highest ticket price is 80." : ""}/>The app owns the message and clears it: a form reset leaves it in place. In Flutter, the validator’s message clears on form reset.
Accessibility
Section titled “Accessibility”- Two native
<input type="range">elements: the browser provides each thumb’s slider role, ARIA value, Arrow / Home / End / PageUp / PageDown control, pointer dragging and form submission. labelnames the group;thumbLabelsnames each thumb, because there is no universal wording for “the lower one” to fall back to.- Each thumb reports the bound it may not cross in two ways. An explicit
aria-valuemin/aria-valuemaxoverride carries it as numbers; ARIA in HTML discourages this override on a native range input, and the attributes being present is not proof that every accessibility tree or assistive technology honours them over the input’s ownminandmax.aria-valuetexttherefore carries the same constraint as text: it is permitted on a native range input, so it does not depend on the override being honoured, though what an engine exposes is still the engine’s. WAI-ARIA supplies the normative role and state requirements here; the Authoring Practices supply the pattern guidance. - What real assistive technology announces, and how touch assistive technology reaches stacked thumbs, are not verified by the automated suites: that validation belongs to the final manual accessibility session (A1).
- The thumb is 24 × 24 CSS pixels by default, the smallest pointer target WCAG 2.2 accepts.
- A non-empty
erroraddsaria-invalid="true"and anaria-describedbylink to the message on both inputs.
Both thumbs submit under the same name, in order:
new FormData(form).getAll("price"); // ["20", "80"]A native reset restores the current default pair and reports nothing through onValueChange; in Vue the v-model binding follows the reset, as it does for Slider.
Example
Section titled “Example”<RangeSlider value={[20, 80]} min={0} max={100} step={5} minDistance={10} label="Price range" thumbLabels={["Minimum price", "Maximum price"]} showValue showRange/>In React, the value is a pair and onValueChange reports the whole pair:
<RangeSlider label="Price range" thumbLabels={["Minimum price", "Maximum price"]} value={range} minDistance={10} onValueChange={setRange}/>Themeable via --ds-range-slider-* (length for the horizontal width, vertical-length for the upright track, track-size, thumb-size).