Slider
A control element that allows for a range of selections.
Anatomy
To set up the slider correctly, you'll need to understand its anatomy and how we name its parts.
Each part includes a
data-part
attribute to help identify them in the DOM.
Examples
Learn how to use the Slider
component in your project. Let's take a look at the most basic
example:
import { Slider } from '@ark-ui/react/slider'
export const Basic = () => {
return (
<Slider.Root>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
)
}
import { Slider } from '@ark-ui/solid/slider'
export const Basic = () => {
return (
<Slider.Root>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
)
}
<script setup lang="ts">
import { Slider } from '@ark-ui/vue/slider'
</script>
<template>
<Slider.Root>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb :index="0">
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
</template>
Range Slider
You can add multiple thumbs to the slider by adding multiple Slider.Thumb
Adding marks
You can add marks to the slider track by using the Slider.MarkerGroup
and Slider.Marker
components.
Position the Slider.Marker
components relative to the track by providing the value
prop.
Setting the initial value
To set the slider's initial value, set the defaultValue
prop to the array of numbers.
import { Slider } from '@ark-ui/react/slider'
export const InitialValue = () => (
<Slider.Root defaultValue={[42]}>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
<Slider.MarkerGroup>
<Slider.Marker value={0}>*</Slider.Marker>
<Slider.Marker value={30}>*</Slider.Marker>
<Slider.Marker value={60}>*</Slider.Marker>
</Slider.MarkerGroup>
</Slider.Root>
)
import { Slider } from '@ark-ui/solid/slider'
export const InitialValue = () => (
<Slider.Root value={[42]}>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
<Slider.MarkerGroup>
<Slider.Marker value={0}>*</Slider.Marker>
<Slider.Marker value={30}>*</Slider.Marker>
<Slider.Marker value={60}>*</Slider.Marker>
</Slider.MarkerGroup>
</Slider.Root>
)
<script setup lang="ts">
import { Slider } from '@ark-ui/vue/slider'
</script>
<template>
<Slider.Root :model-value="[42]">
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb :index="0">
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
<Slider.MarkerGroup>
<Slider.Marker :value="0">*</Slider.Marker>
<Slider.Marker :value="30">*</Slider.Marker>
<Slider.Marker :value="60">*</Slider.Marker>
</Slider.MarkerGroup>
</Slider.Root>
</template>
Specifying the minimum and maximum
By default, the minimum is 0
and the maximum is 100
. If that's not what you want, you can easily
specify different bounds by changing the values of the min
and/or max
props.
For example, to ask the user for a value between -10
and 10
, you can use:
import { Slider } from '@ark-ui/react/slider'
export const MinMax = () => {
return (
<Slider.Root min={-10} max={10}>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
)
}
import { Slider } from '@ark-ui/solid/slider'
export const MinMax = () => {
return (
<Slider.Root min={-10} max={10}>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
)
}
<script setup lang="ts">
import { Slider } from '@ark-ui/vue/slider'
</script>
<template>
<Slider.Root :min="-10" :max="10">
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb :key="0" :index="0" >
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
</template>
Setting the value's granularity
By default, the granularity, is 1
, meaning that the value is always an integer. You can change the
step attribute to control the granularity.
For example, If you need a value between 5
and 10
, accurate to two decimal places, you should
set the value of step to 0.01
:
import { Slider } from '@ark-ui/react/slider'
export const Step = () => {
return (
<Slider.Root step={0.01} min={5} max={10}>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
)
}
import { Slider } from '@ark-ui/solid/slider'
export const Step = () => {
return (
<Slider.Root step={0.01} min={5} max={10}>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
)
}
<script setup lang="ts">
import { Slider } from '@ark-ui/vue/slider'
</script>
<template>
<Slider.Root :step="0.01" :min="5" :max="10">
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb :index="0">
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
</template>
Listening for changes
When the slider value changes, the onValueChange
and onValueChangeEnd
callbacks are invoked. You
can use this to set up custom behaviors in your app.
import { Slider } from '@ark-ui/react/slider'
export const OnEvent = () => {
return (
<Slider.Root
onValueChange={(details) => console.log(details.value)}
onValueChangeEnd={(details) => console.log(details.value)}
>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
)
}
import { Slider } from '@ark-ui/solid/slider'
export const OnEvent = () => {
return (
<Slider.Root
onValueChange={(details) => console.log(details.value)}
onValueChangeEnd={(details) => console.log(details.value)}
>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
)
}
<script setup lang="ts">
import { Slider } from '@ark-ui/vue/slider'
</script>
<template>
<Slider.Root
@value-change="(details) => console.log(details.value)"
@value-change-end="(details) => console.log(details.value)"
>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb :index="0">
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
</template>
Changing the orientation
By default, the slider is assumed to be horizontal. To change the orientation to vertical, set the orientation property in the machine's context to vertical.
In this mode, the slider will use the arrow up and down keys to increment/decrement its value.
Don't forget to change the styles of the vertical slider by specifying its height
import { Slider } from '@ark-ui/react/slider'
export const Vertical = () => {
return (
<Slider.Root orientation="vertical">
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
)
}
import { Slider } from '@ark-ui/solid/slider'
export const Vertical = () => {
return (
<Slider.Root orientation="vertical">
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
)
}
<script setup lang="ts">
import { Slider } from '@ark-ui/vue/slider'
</script>
<template>
<Slider.Root orientation="vertical">
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb :index="0" >
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
</template>
Changing the origin
By default, the slider's origin is at the start of the track. To change the origin to the center of
the track, set the origin
prop to center
.
import { Slider } from '@ark-ui/react/slider'
export const CenterOrigin = () => {
return (
<Slider.Root origin="center">
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
)
}
import { Slider } from '@ark-ui/solid/slider'
export const CenterOrigin = () => {
return (
<Slider.Root origin="center">
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
)
}
<script setup lang="ts">
import { Slider } from '@ark-ui/vue/slider'
</script>
<template>
<Slider.Root origin="center">
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb :index="0">
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.Root>
</template>
Using the Root Provider
The RootProvider
component provides a context for the slider. It accepts the value of the useSlider
hook.
You can leverage it to access the component state and methods from outside the slider.
import { Slider, useSlider } from '@ark-ui/react/slider'
export const RootProvider = () => {
const slider = useSlider()
return (
<>
<button onClick={() => slider.focus()}>Focus</button>
<Slider.RootProvider value={slider}>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.RootProvider>
</>
)
}
import { Slider, useSlider } from '@ark-ui/solid/slider'
export const RootProvider = () => {
const slider = useSlider()
return (
<>
<button onClick={() => slider().focus()}>Focus</button>
<Slider.RootProvider value={slider}>
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb index={0}>
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.RootProvider>
</>
)
}
<script setup lang="ts">
import { Slider, useSlider } from '@ark-ui/vue/slider'
const slider = useSlider()
</script>
<template>
<button @click="slider.focus()">Focus</button>
<Slider.RootProvider :value="slider">
<Slider.Label>Label</Slider.Label>
<Slider.ValueText />
<Slider.Control>
<Slider.Track>
<Slider.Range />
</Slider.Track>
<Slider.Thumb :index="0">
<Slider.HiddenInput />
</Slider.Thumb>
</Slider.Control>
</Slider.RootProvider>
</template>
If you're using the
RootProvider
component, you don't need to use theRoot
component.
API Reference
Root
Prop | Default | Type |
---|---|---|
aria-label | string[] The aria-label of each slider thumb. Useful for providing an accessible name to the slider | |
aria-labelledby | string[] The `id` of the elements that labels each slider thumb. Useful for providing an accessible name to the slider | |
asChild | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. | |
defaultValue | number[] The initial value of the slider when it is first rendered. Use when you do not need to control the state of the slider picker. | |
disabled | boolean Whether the slider is disabled | |
form | string The associate form of the underlying input element. | |
getAriaValueText | (details: ValueTextDetails) => string Function that returns a human readable value for the slider thumb | |
id | string The unique identifier of the machine. | |
ids | Partial<{
root: string
thumb(index: number): string
hiddenInput(index: number): string
control: string
track: string
range: string
label: string
valueText: string
marker(index: number): string
}> The ids of the elements in the range slider. Useful for composition. | |
invalid | boolean Whether the slider is invalid | |
max | 100 | number The maximum value of the slider |
min | 0 | number The minimum value of the slider |
minStepsBetweenThumbs | 0 | number The minimum permitted steps between multiple thumbs. |
name | string The name associated with each slider thumb (when used in a form) | |
onFocusChange | (details: FocusChangeDetails) => void Function invoked when the slider's focused index changes | |
onValueChange | (details: ValueChangeDetails) => void Function invoked when the value of the slider changes | |
onValueChangeEnd | (details: ValueChangeDetails) => void Function invoked when the slider value change is done | |
orientation | 'horizontal' | 'horizontal' | 'vertical' The orientation of the slider |
origin | 'start' | 'center' | 'start' The origin of the slider range - "start": Useful when the value represents an absolute value - "center": Useful when the value represents an offset (relative) |
readOnly | boolean Whether the slider is read-only | |
step | 1 | number The step value of the slider |
thumbAlignment | 'contain' | 'center' | 'contain' The alignment of the slider thumb relative to the track - `center`: the thumb will extend beyond the bounds of the slider track. - `contain`: the thumb will be contained within the bounds of the track. |
thumbSize | { width: number; height: number } The slider thumbs dimensions | |
value | number[] The value of the range slider |
Data Attribute | Value |
---|---|
[data-scope] | slider |
[data-part] | root |
[data-disabled] | Present when disabled |
[data-orientation] | The orientation of the slider |
[data-dragging] | Present when in the dragging state |
[data-invalid] | Present when invalid |
[data-focus] | Present when focused |
Control
Prop | Default | Type |
---|---|---|
asChild | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
Data Attribute | Value |
---|---|
[data-scope] | slider |
[data-part] | control |
[data-dragging] | Present when in the dragging state |
[data-disabled] | Present when disabled |
[data-orientation] | The orientation of the control |
[data-invalid] | Present when invalid |
[data-focus] | Present when focused |
DraggingIndicator
Prop | Default | Type |
---|---|---|
asChild | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
HiddenInput
Prop | Default | Type |
---|---|---|
asChild | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
Label
Prop | Default | Type |
---|---|---|
asChild | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
Data Attribute | Value |
---|---|
[data-scope] | slider |
[data-part] | label |
[data-disabled] | Present when disabled |
[data-orientation] | The orientation of the label |
[data-invalid] | Present when invalid |
[data-dragging] | Present when in the dragging state |
[data-focus] | Present when focused |
MarkerGroup
Prop | Default | Type |
---|---|---|
asChild | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
Data Attribute | Value |
---|---|
[data-scope] | slider |
[data-part] | marker-group |
[data-orientation] | The orientation of the markergroup |
Marker
Prop | Default | Type |
---|---|---|
value | number | |
asChild | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
Data Attribute | Value |
---|---|
[data-scope] | slider |
[data-part] | marker |
[data-orientation] | The orientation of the marker |
[data-value] | |
[data-disabled] | Present when disabled |
[data-state] |
Range
Prop | Default | Type |
---|---|---|
asChild | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
Data Attribute | Value |
---|---|
[data-scope] | slider |
[data-part] | range |
[data-dragging] | Present when in the dragging state |
[data-focus] | Present when focused |
[data-invalid] | Present when invalid |
[data-disabled] | Present when disabled |
[data-orientation] | The orientation of the range |
RootProvider
Prop | Default | Type |
---|---|---|
value | UseSliderReturn | |
asChild | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
Thumb
Prop | Default | Type |
---|---|---|
index | number | |
asChild | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. | |
name | string |
Data Attribute | Value |
---|---|
[data-scope] | slider |
[data-part] | thumb |
[data-index] | The index of the item |
[data-name] | |
[data-disabled] | Present when disabled |
[data-orientation] | The orientation of the thumb |
[data-focus] | Present when focused |
[data-dragging] | Present when in the dragging state |
Track
Prop | Default | Type |
---|---|---|
asChild | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
Data Attribute | Value |
---|---|
[data-scope] | slider |
[data-part] | track |
[data-disabled] | Present when disabled |
[data-invalid] | Present when invalid |
[data-dragging] | Present when in the dragging state |
[data-orientation] | The orientation of the track |
[data-focus] | Present when focused |
ValueText
Prop | Default | Type |
---|---|---|
asChild | boolean Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
Data Attribute | Value |
---|---|
[data-scope] | slider |
[data-part] | value-text |
[data-disabled] | Present when disabled |
[data-orientation] | The orientation of the valuetext |
[data-invalid] | Present when invalid |
[data-focus] | Present when focused |
Accessibility
Complies with the Slider WAI-ARIA design pattern.
Keyboard Support
Key | Description |
---|---|
ArrowRight | Increments the slider based on defined step |
ArrowLeft | Decrements the slider based on defined step |
ArrowUp | Increases the value by the step amount. |
ArrowDown | Decreases the value by the step amount. |
PageUp | Increases the value by a larger step |
PageDown | Decreases the value by a larger step |
Shift + ArrowUp | Increases the value by a larger step |
Shift + ArrowDown | Decreases the value by a larger step |
Home | Sets the value to its minimum. |
End | Sets the value to its maximum. |