<c-slider>
A slider for picking a number from a range by dragging a thumb along a track, with a label, a value bubble and optional tick marks.
Usage
Set the range with min, max and step (0, 100 and 1 by default) and bind
the value:
<c-slider v-model="volume" label="Volume" unit="%" />
When to use
- Picking a value in a bounded range where the position on the track helps the user judge it: a volume, a percentage, a small count with tick marks.
- For an exact number, or a range too wide to drag through precisely, use
c-number-field.
Value
The value is a number between min and max. While the thumb is dragged,
update:value and input fire on every move; change fires once, on the
release that ends the drag, and on each key press that moves the thumb. Save
or fetch on change rather than on every move:
<c-slider
:value="cores"
label="CPU cores"
max="8"
@change="cores = $event.detail"
/>
Setting value moves the thumb and fires nothing. Set one: the built-in
default is 50 whatever min and max are, held within them, so a slider
with max="8" and no value starts at 8.
In a native <form> the value submits under name; see In a form on
c-button.
Value bubble and unit
While the slider is hovered, pressed or focused, a bubble above the thumb shows
the value followed by unit, written with as many decimals as step has and
the separators of the page's lang (2,5 for fi, 2.5 for en). The unit
is appended as written, so include a space where one belongs (unit=" GB").
Set disable-tooltip to turn the bubble off.
Tick marks
ticks draws marks along the track, dividing it into segments equal parts
(ten by default) from min to max, and tick-labels writes a number under
each mark, formatted like the bubble's (the 3.x labels still does until 5.0). The marks are
independent of step: for a mark on every value, match segments to the
range.
<c-slider
label="Cores"
max="8"
segments="8"
value="2"
tick-labels
ticks
></c-slider>
Accessibility
The control is a native <input type="range">, so it is announced as a slider
and works from the keyboard: the arrow keys move it one step, Home and End
jump to min and max. The value is announced with its unit.
Name it with label, which renders a visible label for the range input.
Without a visible label, set aria-label on the c-slider element; it names
the range input instead. The bubble, the marks and their numbers are hidden
from assistive technology.
Customization
Restyle via CSS parts: ::part(root) wraps the label, the range input and the
track; ::part(label) is the label; ::part(ticks) is the visible track under
the thumb, carrying the fill and the tick marks. The thumb and the fill paint
the primary role, and a disabled slider greys them out; re-theme through the
tokens.
Examples
<template>
<div>
<c-slider v-model="volume" label="Volume" unit="%" />
<p>Value: {{ volume }} %</p>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const volume = ref(40);
</script>
<template>
<div>
<c-slider
v-model="cores"
label="CPU cores"
max="8"
min="0"
segments="8"
step="1"
tick-labels
ticks
/>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const cores = ref(2);
</script>
API reference
<c-slider>
A slider for picking a number from a range by dragging a thumb along a track, with a label, a value bubble and optional tick marks.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Disable the slider |
disableTooltip | disable-tooltip | boolean | false | Turn off the value bubble shown above the thumb while the slider is hovered, pressed or focused |
label | label | string | '' | Label of the slider |
max | max | number | 100 | The largest value. |
min | min | number | 0 | The smallest value. |
name | name | string | '' | The name the value submits under in a native `<form>` |
segments | segments | number | 10 | Number of segments the tick marks divide the track into. |
step | step | number | 1 | Step between values. |
tickLabels | tick-labels | boolean | — | Write a number under the track at each tick mark position, `segments` apart, formatted like the value bubble's; shown with or without `ticks` |
ticks | ticks | boolean | false | Draw tick marks along the track, `segments` apart. |
unit | unit | string | '' | Unit shown after the value in the tooltip and read with it, e.g. `%`. |
value | value | number | 50 | The value, a number between `min` and `max`. |
labels deprecated | labels | boolean | false | Deprecated. Use `tick-labels`. Write a number under the track at each tick mark position, `segments` apart, formatted like the value bubble's; shown with or without `ticks` |
Events
| Event | Detail | Description |
|---|---|---|
change | number | Fired when a move is committed — the release that ends a drag, or each arrow-key step — carrying the value. |
input | void | Native bubbling input event fired on every thumb movement so a plain Vue `v-model` stays in sync. No detail. |
update:value | number | v-model contract event fired on every thumb movement, carrying the new value. |
Methods
| Method | Signature | Description |
|---|---|---|
focus | (options?: FocusOptions): void | Focus its slider, as `focus()` does on a native control: the element renders no box of its own to take it. |
CSS parts
Style from outside with c-slider::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The outer wrapper containing the label, range input and track |
label | The label element rendered above the slider |
ticks | The visible track below the input, carrying the progress fill and tick marks |