Slider
A headless, accessible slider with single- or multi-thumb selection, keyboard support, and horizontal/vertical orientation.
Features
- Horizontal or vertical
- Single or multi-thumb
- Controlled or uncontrolled
- Keyboard and pointer support
- Headless
Installation
npm install @ariaui/slider
Examples
Three playgrounds aligned with the legacy doc: an uncontrolled single thumb (100–200 with a CSS tooltip), a two-thumb range on 0–100, and a vertical track.
Shared class strings live in sliderExampleTokens.ts; each block is a static defaultValue tree so the generated snippet stays copy-pasteable.
Uncontrolled
Single thumb with a static defaultValue. This docs variant uses the thumb's aria-valuenow as a CSS tooltip so the snippet stays copy-pasteable without extra state.
No preview output yet.
Controlled
Drive the slider from React state with value and onValueChange, while rendering the current value next to the thumb state.
No preview output yet.
Disabled
Set isDisabled on the root to lock every thumb and expose disabled state attributes for styling.
No preview output yet.
Multi-thumb
Two thumbs share the same track to create a range. This example starts at [30, 70] and uses each thumb's aria-valuenow as a CSS tooltip.
No preview output yet.
Custom Tooltip
getValueText maps the numeric value to aria-valuetext, and the thumb tooltip reads that attribute for a custom visible label.
No preview output yet.
Vertical
Set orientation="vertical" on the root to switch axes. The track becomes a tall rail while the range fill and thumb labels adapt to the vertical layout.
No preview output yet.
Vertical Multi-thumb
Combine orientation="vertical" with two thumbs to select a vertical range. The thumb tooltips read from aria-valuenow, so dragging updates the visible values.
No preview output yet.
Anatomy
import * as Slider from "@ariaui/slider";
export default function Example() {
return (
<Slider.Root>
<Slider.Track>
<Slider.Range />
<Slider.Thumb />
</Slider.Track>
</Slider.Root>
);
}
API Reference
Root
Slider context provider and state container. Handles controlled/uncontrolled values, step constraints, and orientation.
| Prop | Type | Default |
|---|---|---|
value | number | number[] | — |
defaultValue | number | number[] | min |
onValueChange | (value: number | number[]) => void | — |
min | number | 0 |
max | number | 100 |
step | number | 1 |
minStepsBetweenThumbs | number | 0 |
orientation | 'horizontal' | 'vertical' | 'horizontal' |
isDisabled | boolean | false |
getValueText | (value: number) => string | — |
name | string | — |
| Attribute | Values |
|---|---|
| data-orientation | 'horizontal' | 'vertical' |
| data-disabled | present when disabled |
Track
Background rail that hosts the Range and Thumbs. Clicks and drags on the track move the nearest thumb.
| Attribute | Values |
|---|---|
| data-orientation | 'horizontal' | 'vertical' |
| data-disabled | present when disabled |
Range
Filled portion of the Track between `min` (or the previous thumb) and the current thumb value.
| Attribute | Values |
|---|---|
| data-orientation | 'horizontal' | 'vertical' |
| data-disabled | present when disabled |
Thumb
Draggable handle that represents a value. Render one Thumb per value in multi-thumb mode and pass `index`.
| Prop | Type | Default |
|---|---|---|
index | number | 0 |
| Attribute | Values |
|---|---|
| role | 'slider' |
| aria-valuenow | current value of the thumb |
| aria-valuemin | min |
| aria-valuemax | max |
| aria-valuetext | getValueText(value) when provided |
| aria-orientation | 'horizontal' | 'vertical' |
| data-active | true while dragging or focused |
| data-disabled | present when disabled |
Keyboard
| Shortcut | Action |
|---|---|
| Tab | Move focus to the next thumb (or away from the slider). |
| Shift+Tab | Move focus to the previous thumb. |
| →/↑ | Increase the focused thumb by one step. |
| ←/↓ | Decrease the focused thumb by one step. |
| PageUp | Increase the focused thumb by a larger increment. |
| PageDown | Decrease the focused thumb by a larger increment. |
| Home | Set the focused thumb to `min`. |
| End | Set the focused thumb to `max`. |
Accessibility
Slider follows the WAI-ARIA Slider pattern (or multi-thumb Slider pattern when more than one Thumb is present):
- Each
Thumbrenders withrole="slider"and exposesaria-valuenow,aria-valuemin,aria-valuemax, andaria-orientation. - Provide
getValueTexton Root to deliver meaningfularia-valuetextvalues (e.g."$25.00"or"25 percent") — especially important when the raw number isn't self-descriptive. - Always label the slider. Pass
aria-labeloraria-labelledbyon Root, or wire up an external<label>to the thumb viaaria-labelledby. - Keyboard users get full control: arrow keys for fine adjustments, Page Up / Page Down for coarse steps, Home / End for the range bounds, and Tab to move between thumbs.
minStepsBetweenThumbsprevents multi-thumb sliders from crossing or overlapping without explicit intent.- When
isDisabledis true,data-disabledis set on every part for styling and pointer and keyboard interactions are disabled.