Slider
Overview
A slider for picking one or more numeric values within a continuous range, supporting horizontal and vertical orientations, multi-thumb range mode, RTL and inverted directions, and complete keyboard navigation. Use it when the value belongs to a bounded numeric range and the user should adjust it with mouse or keyboard precision; when the value is free-form text or numbers, prefer SInputNumber instead.
Usage
Features
- 🎚
modelValue/defaultValue— controlled and uncontrolled modes backed byuseControllableState - 🔢 Single or multi-thumb range — pass an array with two values for a range slider
- ⌨️ Full keyboard support — Arrow keys step by
step, PageUp/PageDown and Shift+Arrow jump 10 steps, Home/End go to min/max - ↔ RTL-aware direction with
dir, plusinvertedto flip the value direction - 📐 Horizontal and vertical orientations with
aria-orientationreflection - 📋 Native form proxy — a visually hidden input (or
name[0]/name[1]pair for ranges) carries the value withname/required - 🎨 6 sizes and 8 colors via
sliderVariants - 🧩
trackProps/rangeProps/thumbPropsforwarding plus a default slot to customize thumb content - 📏
minStepsBetweenThumbsandthumbAlignment(contain/overflow) for precise range control
Demos
Basic
100%
40
API
Aria Layer
6Slider
22 Props2 Emits
Props
| Prop | Type | Default | Description |
|---|---|---|---|
class | ClassValue | — | Additional class names applied to the root element. |
color | ThemeColor | — | Theme color of the component. |
size | ThemeSize | — | Visual size of the component. |
ui | Partial<SliderUi> | — | Per-slot class overrides for the component. |
trackProps | SliderTrackProps | — | Properties forwarded to the track element. |
rangeProps | SliderRangeProps | — | Properties forwarded to the range element. |
thumbProps | BaseProps | — | Properties forwarded to the thumb element. |
modelValue | number[] | — | The controlled value of the slider. Can be bind as `v-model`. |
defaultValue | number[] | — | The initial value of the slider when uncontrolled. |
disabled | boolean | — | Whether the slider is disabled. |
orientation | DataOrientation | — | The orientation of the slider. |
dir | Direction | — | The reading direction of the slider. |
inverted | boolean | — | Whether the slider value direction is inverted. |
min | number | — | The minimum value. |
max | number | — | The maximum value. |
step | number | — | The stepping interval. |
minStepsBetweenThumbs | number | — | The minimum permitted steps between multiple thumbs. |
thumbAlignment | SliderThumbAlignment | — | Whether thumbs stay within the track bounds or may overflow it. |
name | string | — | The name of the field. Submitted with its owning form as part of a name/value pair. |
required | boolean | — | When `true`, indicates that the user must set the value before the owning form can be submitted. |
asChild | boolean | — | Change the default rendered element for the one passed as a child, merging their props and behavior. |
as | AsTag | Component | 'div' | The element or component this component should render as. Can be overwrite by `asChild` |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
update:modelValue | number[] | Event handler called when the slider value changes. |
valueCommit | number[] | Event handler called when a slider interaction is committed. |
SliderCompact
18 Props2 Emits1 Slots
Props
| Prop | Type | Default | Description |
|---|---|---|---|
trackProps | SliderTrackProps | — | Properties forwarded to the track element. |
rangeProps | SliderRangeProps | — | Properties forwarded to the range element. |
thumbProps | BaseProps | — | Properties forwarded to the thumb element. |
modelValue | number[] | — | The controlled value of the slider. Can be bind as `v-model`. |
defaultValue | number[] | — | The initial value of the slider when uncontrolled. |
disabled | boolean | — | Whether the slider is disabled. |
orientation | DataOrientation | — | The orientation of the slider. |
dir | Direction | — | The reading direction of the slider. |
inverted | boolean | — | Whether the slider value direction is inverted. |
min | number | — | The minimum value. |
max | number | — | The maximum value. |
step | number | — | The stepping interval. |
minStepsBetweenThumbs | number | — | The minimum permitted steps between multiple thumbs. |
thumbAlignment | SliderThumbAlignment | — | Whether thumbs stay within the track bounds or may overflow it. |
name | string | — | The name of the field. Submitted with its owning form as part of a name/value pair. |
required | boolean | — | When `true`, indicates that the user must set the value before the owning form can be submitted. |
asChild | boolean | — | Change the default rendered element for the one passed as a child, merging their props and behavior. |
as | AsTag | Component | 'div' | The element or component this component should render as. Can be overwrite by `asChild` |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
update:modelValue | number[] | Event handler called when the slider value changes. |
valueCommit | number[] | Event handler called when a slider interaction is committed. |
Slots
| Slot Name | Parameters | Description |
|---|---|---|
default | SliderCompactSlotProps | Custom content for the default slot. |
SliderRange
2 Props
Props
| Prop | Type | Default | Description |
|---|---|---|---|
asChild | boolean | — | Change the default rendered element for the one passed as a child, merging their props and behavior. |
as | AsTag | Component | 'div' | The element or component this component should render as. Can be overwrite by `asChild` |
SliderRoot
15 Props2 Emits
Props
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | number[] | — | The controlled value of the slider. Can be bind as `v-model`. |
defaultValue | number[] | — | The initial value of the slider when uncontrolled. |
disabled | boolean | — | Whether the slider is disabled. |
orientation | DataOrientation | — | The orientation of the slider. |
dir | Direction | — | The reading direction of the slider. |
inverted | boolean | — | Whether the slider value direction is inverted. |
min | number | — | The minimum value. |
max | number | — | The maximum value. |
step | number | — | The stepping interval. |
minStepsBetweenThumbs | number | — | The minimum permitted steps between multiple thumbs. |
thumbAlignment | SliderThumbAlignment | — | Whether thumbs stay within the track bounds or may overflow it. |
name | string | — | The name of the field. Submitted with its owning form as part of a name/value pair. |
required | boolean | — | When `true`, indicates that the user must set the value before the owning form can be submitted. |
asChild | boolean | — | Change the default rendered element for the one passed as a child, merging their props and behavior. |
as | AsTag | Component | 'div' | The element or component this component should render as. Can be overwrite by `asChild` |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
update:modelValue | number[] | Event handler called when the slider value changes. |
valueCommit | number[] | Event handler called when a slider interaction is committed. |
SliderThumb
3 Props
Props
| Prop | Type | Default | Description |
|---|---|---|---|
index | number | — | The thumb index in the current slider value array. |
asChild | boolean | — | Change the default rendered element for the one passed as a child, merging their props and behavior. |
as | AsTag | Component | 'div' | The element or component this component should render as. Can be overwrite by `asChild` |
SliderTrack
2 Props
Props
| Prop | Type | Default | Description |
|---|---|---|---|
asChild | boolean | — | Change the default rendered element for the one passed as a child, merging their props and behavior. |
as | AsTag | Component | 'div' | The element or component this component should render as. Can be overwrite by `asChild` |
Notes
Architecture and benchmark differences
VeanUI builds the slider from Aria SliderRoot (useControllableState + value normalization + VisuallyHiddenInput form proxy) → SliderTrack (pointer drag, pointer-move/up/cancel on the document) → SliderRange (percentage span between thumbs) → SliderThumb (role="slider" + aria-valuemin/max/now + aria-orientation, focus-derived step navigation). SliderCompact composes root + track + range + thumbs and owns thumb iteration; the UI wrapper SSlider only computes variant classes via sliderVariants and injects the ui map through provideSliderUi.
| Capability | VeanUI | Ant Design Slider | Element Plus Slider | Mantine Slider | Naive UI Slider | shadcn Slider |
|---|---|---|---|---|---|---|
| Aria/styled split | ✅ | — | — | — | — | ✅ |
| Controlled/uncontrolled | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Range (multi-thumb) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Vertical orientation | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Inverted / RTL | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Keyboard nav (Arrows/Home/End/Page) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
minStepsBetweenThumbs | ✅ | — | — | — | — | ✅ |
Form proxy / name submit | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Axe-clean | ✅ | — | — | — | — | — |
| Marks (scale ticks) | ➕ | ✅ | ✅ | ✅ | ✅ | — |
| Value tooltip while dragging | ➕ | ✅ | ✅ | ✅ | ✅ | — |
| Linked number input | ➕ | ✅ | — | — | — | — |
Cautions
- A single thumb has no default accessible name — pass
aria-labelthroughthumbProps(range mode falls back to localized “Minimum”/“Maximum” labels automatically). - Thumbs default to
containinside the track;thumbAlignment="overflow"lets them extend beyond the track bounds. - The form proxy renders only when
nameis present on aform-classed root; pair it with a native<form>or theSFormintegration. - PageUp/PageDown and Shift+Arrow keys step 10× the
stepvalue;minStepsBetweenThumbsblocks thumbs from crossing each other.
FAQ
How do I create a range slider?
Pass an array with two values to modelValue (or defaultValue), e.g. [20, 80]. Two thumbs are rendered and valueCommit emits both values. Each thumb is labeled “Minimum”/“Maximum” (localized) unless you override thumbProps['aria-label'].
How do I keep the two thumbs apart?
Set minStepsBetweenThumbs to the minimum number of steps between thumbs — stepping or dragging is rejected when the gap would fall below that threshold.
How do I show the current value above the thumb?
Use the default slot, which receives { index, value, modelValue } for each thumb, to render custom content. A built-in tooltip is a planned enhancement.
What keyboard shortcuts are supported?
Arrow keys step by step, PageUp/PageDown and Shift+Arrow jump 10 steps, and Home/End jump to min/max. Direction keys follow dir and inverted (RTL flips horizontal arrows; inverted flips the value direction).