Slider
updatedSlide to unlock. Just kidding, slide to pick.
Open Props in the corner of the example to try variant, color, size, disabled and aria-invalid. A disabled slider turns grey and ignores the pointer and the keyboard. An invalid one turns its range and thumbs --destructive, whatever its color, and sets aria-invalid on each thumb.
size sets the handle, from 12px for xs to 24px for xl, and the track thickness with it, from 4px to 10px. md, the default, is a 16px thumb on a 6px track.
color draws the range and the thumbs in Button's colours or your own, primary by default. On the default track they sit on the page, so they take the colour's text shade, and the rest of the track is the colour at 20%. An inset thumb carries its handle, so it and the range keep the fill colour, and the track stays grey.
Installation
Usage
<script setup lang="ts">
import { Slider } from '@/components/ui/slider'
const volume = ref(50)
</script>
<template>
<Slider v-model="volume" aria-label="Volume" />
</template>
v-model is a number for one thumb. Pass an array, and you get one thumb per item.
Click anywhere on the track, and the nearest thumb jumps there. The thumb looks and reacts like the Switch handle.
Give it an aria-label, or put it in a Field.
Set name, and the value submits with its form, one field per thumb named name[0], name[1] and so on, a single thumb included: a slider named volume posts volume[0]=50. Rails and PHP read that as an array.
Examples
Min, max and step
The value runs from min to max, 0 to 100 by default, in steps of step. When the number alone does not say what it means, set aria-valuetext, which screen readers read instead.
From 16 to 28 °C in steps of 0.5.
Multiple
Pass an array for a range, like a price filter. Each thumb gets a screen reader name on its own, so you don't need to label them one by one.
Min steps between thumbs
min-steps-between-thumbs keeps neighbouring thumbs that many steps apart. Without it, thumbs can meet and pass each other.
At least 4 hours apart.
Orientation
orientation="vertical" runs the slider from bottom to top. It fills the height of its container and is at least 176px tall.
Inset
variant="inset" puts the thumb inside a thick track, with the fill wrapping around it. The handle shrinks a little while you drag it.
Keep the default thumb-alignment="contain". With overflow, the fill and the handle drift apart near the ends.
Inverted
Same slider, but in Australia. inverted flips it: right to left, or top to bottom. Arrow keys still move the thumb the way they point.
On a right-to-left page, a horizontal slider already runs right to left on its own.
Touch target
Smaller than a finger? Add touch-target: expand when it stands alone, wrapper when it sits close to others. How it works.
The track and each thumb get their own area: press a thumb's to pick it up where it is, or the track's to pull the nearest thumb to your finger.
Parts
Need a look the props don't cover? Lay the slider out yourself: a SliderTrack holding a SliderRange, and a SliderThumb per value, each with a SliderHandle inside unless you put something else there. Every part takes a class. The slot gives you thumbs and values, so a range can loop: <SliderThumb v-for="i in thumbs" :key="i" />.
Give each thumb of a range its own aria-label when the defaults, Minimum and Maximum, don't say enough.
API Reference
class is also accepted and merged over the base classes.
Slider
| Prop | Default | Type and description |
|---|---|---|
| disabled | — | booleanDisables the slider. Also set by a disabled field. |
| orientation | — | DataOrientation
|
| dir | — | DirectionReading direction. In |
| inverted | — | booleanRuns the slider from the other end, right to left or top to bottom. |
| min | — | numberThe lowest value. |
| max | — | numberThe highest value. |
| step | — | numberThe interval values snap to. |
| minStepsBetweenThumbs | — | numberHow many steps apart neighbouring thumbs must stay. |
| thumbAlignment | — | ThumbAlignment
|
| name | — | stringSubmits the value with its form, one field per thumb named |
| required | — | booleanMarks the slider required. Also set by a required field. |
| id | — | stringOverrides the |
| defaultValue | — | number | number[]The starting value when |
| variant | — | "default" | "inset" | null
|
| color | "primary" | SliderColor | (string & {})Colour role of the range and thumbs, and of the default track at 20%. Any other name picks up a colour you declare on |
| size | "md" | SliderSizeHandle diameter, from 12px for |
| touchTarget | — | "none" | "expand" | "wrapper" | nullGrows the pressable area of the track and each thumb to at least 48px without changing how the slider looks. |
| modelValue | — | number | number[]The value, bound with |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: number | number[] | undefined]Fires as a thumb moves. |
| valueCommit | [value: number | number[]]Fires once when a drag or key press ends, with the final value in the same shape as |
| Slot | Scope and description |
|---|---|
| default | { thumbs: number; values: number[]; }The parts, when you lay them out yourself: a |
SliderTrack
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging the track's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The range, a |
SliderRange
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging the range's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
SliderThumb
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging the thumb's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | anyWhat the thumb holds, a |
SliderHandle
No props, events, slots or exposed members.
Props
- disabled
booleanDisables the slider. Also set by a disabled field.- orientation
DataOrientationverticalruns the slider from bottom to top and fills the height of its container.- dir
DirectionReading direction. Inrtla horizontal slider runs right to left.- inverted
booleanRuns the slider from the other end, right to left or top to bottom.- min
numberThe lowest value.- max
numberThe highest value.- step
numberThe interval values snap to.- minStepsBetweenThumbs
numberHow many steps apart neighbouring thumbs must stay.- thumbAlignment
ThumbAlignmentcontainkeeps the thumbs inside the track at both ends;overflowcentres them on the ends.- name
stringSubmits the value with its form, one field per thumb namedname[0],name[1]and so on, a single thumb included.- required
booleanMarks the slider required. Also set by a required field.- id
stringOverrides theidtaken from a surrounding field.- defaultValue
number | number[]The starting value whenv-modelis not used. Falls back tomin.- variant
"default" | "inset" | nullinsetputs each thumb inside a thick track as a disc around a round handle;defaultis a solid thumb over a thin track.- color
"primary" SliderColor | (string & {})Colour role of the range and thumbs, and of the default track at 20%. Any other name picks up a colour you declare on[data-slot][data-color="<name>"]. An invalid slider turnsdestructivewhatever its colour.- size
"md" SliderSizeHandle diameter, from 12px forxsto 24px forxl; the track thickness scales with it.- touchTarget
"none" | "expand" | "wrapper" | nullGrows the pressable area of the track and each thumb to at least 48px without changing how the slider looks.wrapperalso reserves that space in layout;expandmay overlap neighbours.- modelValue
number | number[]The value, bound withv-model. A number for one thumb, an array for one thumb per item.
Emits
- update:modelValue
[value: number | number[] | undefined]Fires as a thumb moves.- valueCommit
[value: number | number[]]Fires once when a drag or key press ends, with the final value in the same shape asv-model.
Slots
- default
{ thumbs: number; values: number[]; }The parts, when you lay them out yourself: aSliderTrackholding aSliderRange, and aSliderThumbper value. Receives{ thumbs, values }, the number of thumbs and the current values. Left out, the slider draws its parts itself.
Props
- asChild
booleanRender the single child instead of a wrapper, merging the track's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The range, aSliderRange.
Props
- asChild
booleanRender the single child instead of a wrapper, merging the range's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Props
- asChild
booleanRender the single child instead of a wrapper, merging the thumb's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
anyWhat the thumb holds, aSliderHandleby default.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| slider | data-orientation, data-disabled, data-touch-target, data-variant, data-color, data-size | The root, and the pressable area of the track. |
| slider-track | data-orientation, data-disabled | The full length of the track. |
| slider-range | data-orientation, data-disabled | The filled part of the track. |
| slider-thumb | data-orientation, data-disabled, data-hovered | One thumb, with role="slider". Draws the state layer, or, with inset, the disc around the handle. |
| slider-handle | — | The circle inside a thumb. |