Ark UI Logo
DocsShowcaseBlogPlus
GitHub
Components
Slider

Slider

A control element that allows for a range of selections.

Loading...

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'
import styles from 'styles/slider.module.css'

export const Basic = () => {
  return (
    <Slider.Root className={styles.Root} defaultValue={[40]}>
      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
        <Slider.Label className={styles.Label}>Label</Slider.Label>
        <Slider.ValueText className={styles.ValueText} />
      </div>
      <Slider.Control className={styles.Control}>
        <Slider.Track className={styles.Track}>
          <Slider.Range className={styles.Range} />
        </Slider.Track>
        <Slider.Thumb index={0} className={styles.Thumb}>
          <Slider.HiddenInput />
        </Slider.Thumb>
      </Slider.Control>
    </Slider.Root>
  )
}

Range Slider

You can add multiple thumbs to the slider by adding multiple Slider.Thumb

import { Slider } from '@ark-ui/react/slider'
import styles from 'styles/slider.module.css'

export const Range = () => {
  return (
    <Slider.Root defaultValue={[30, 60]} className={styles.Root}>
      <Slider.Label className={styles.Label}>Label</Slider.Label>
      <Slider.Control className={styles.Control}>
        <Slider.Track className={styles.Track}>
          <Slider.Range className={styles.Range} />
        </Slider.Track>
        <Slider.Thumb index={0} className={styles.Thumb}>
          <Slider.HiddenInput />
        </Slider.Thumb>
        <Slider.Thumb index={1} className={styles.Thumb}>
          <Slider.HiddenInput />
        </Slider.Thumb>
      </Slider.Control>
    </Slider.Root>
  )
}

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.

import { Slider } from '@ark-ui/react/slider'
import styles from 'styles/slider.module.css'

export const WithMarks = () => {
  return (
    <Slider.Root className={styles.Root} defaultValue={[50]}>
      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
        <Slider.Label className={styles.Label}>Label</Slider.Label>
        <Slider.ValueText className={styles.ValueText} />
      </div>
      <Slider.Control className={styles.Control}>
        <Slider.Track className={styles.Track}>
          <Slider.Range className={styles.Range} />
        </Slider.Track>
        <Slider.Thumb index={0} className={styles.Thumb}>
          <Slider.HiddenInput />
        </Slider.Thumb>
      </Slider.Control>
      <Slider.MarkerGroup className={styles.MarkerGroup}>
        {[0, 25, 50, 75, 100].map((value) => (
          <Slider.Marker key={value} value={value} className={styles.Marker}>
            {value}
          </Slider.Marker>
        ))}
      </Slider.MarkerGroup>
    </Slider.Root>
  )
}

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'
import styles from 'styles/slider.module.css'

export const MinMax = () => {
  return (
    <Slider.Root min={-10} max={10} defaultValue={[5]} className={styles.Root}>
      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
        <Slider.Label className={styles.Label}>Label</Slider.Label>
        <Slider.ValueText className={styles.ValueText} />
      </div>
      <Slider.Control className={styles.Control}>
        <Slider.Track className={styles.Track}>
          <Slider.Range className={styles.Range} />
        </Slider.Track>
        <Slider.Thumb index={0} className={styles.Thumb}>
          <Slider.HiddenInput />
        </Slider.Thumb>
      </Slider.Control>
    </Slider.Root>
  )
}

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'
import styles from 'styles/slider.module.css'

export const Step = () => {
  return (
    <Slider.Root step={0.01} min={5} max={10} defaultValue={[7.5]} className={styles.Root}>
      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
        <Slider.Label className={styles.Label}>Label</Slider.Label>
        <Slider.ValueText className={styles.ValueText} />
      </div>
      <Slider.Control className={styles.Control}>
        <Slider.Track className={styles.Track}>
          <Slider.Range className={styles.Range} />
        </Slider.Track>
        <Slider.Thumb index={0} className={styles.Thumb}>
          <Slider.HiddenInput />
        </Slider.Thumb>
      </Slider.Control>
    </Slider.Root>
  )
}

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'
import styles from 'styles/slider.module.css'

export const OnEvent = () => {
  return (
    <Slider.Root
      onValueChange={(details) => console.log('onValueChange', details.value)}
      onValueChangeEnd={(details) => console.log('onValueChangeEnd', details.value)}
      className={styles.Root}
    >
      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
        <Slider.Label className={styles.Label}>Label</Slider.Label>
        <Slider.ValueText className={styles.ValueText} />
      </div>
      <Slider.Control className={styles.Control}>
        <Slider.Track className={styles.Track}>
          <Slider.Range className={styles.Range} />
        </Slider.Track>
        <Slider.Thumb index={0} className={styles.Thumb}>
          <Slider.HiddenInput />
        </Slider.Thumb>
      </Slider.Control>
    </Slider.Root>
  )
}

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'
import styles from 'styles/slider.module.css'

export const Vertical = () => {
  return (
    <Slider.Root orientation="vertical" className={styles.Root}>
      <Slider.Label className={styles.Label}>Label</Slider.Label>
      <Slider.ValueText className={styles.ValueText} />
      <Slider.Control className={styles.Control}>
        <Slider.Track className={styles.Track}>
          <Slider.Range className={styles.Range} />
        </Slider.Track>
        <Slider.Thumb index={0} className={styles.Thumb}>
          <Slider.HiddenInput />
        </Slider.Thumb>
      </Slider.Control>
    </Slider.Root>
  )
}

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'
import styles from 'styles/slider.module.css'

export const CenterOrigin = () => {
  return (
    <Slider.Root origin="center" className={styles.Root} defaultValue={[75]}>
      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
        <Slider.Label className={styles.Label}>Label</Slider.Label>
        <Slider.ValueText className={styles.ValueText} />
      </div>
      <Slider.Control className={styles.Control}>
        <Slider.Track className={styles.Track}>
          <Slider.Range className={styles.Range} />
        </Slider.Track>
        <Slider.Thumb index={0} className={styles.Thumb}>
          <Slider.HiddenInput />
        </Slider.Thumb>
      </Slider.Control>
    </Slider.Root>
  )
}

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'
import button from 'styles/button.module.css'
import styles from 'styles/slider.module.css'

export const RootProvider = () => {
  const slider = useSlider()

  return (
    <>
      <button className={button.Root} onClick={() => slider.focus()}>
        Focus
      </button>

      <Slider.RootProvider value={slider} className={styles.Root}>
        <Slider.Label className={styles.Label}>Label</Slider.Label>
        <Slider.ValueText className={styles.ValueText} />
        <Slider.Control className={styles.Control}>
          <Slider.Track className={styles.Track}>
            <Slider.Range className={styles.Range} />
          </Slider.Track>
          <Slider.Thumb index={0} className={styles.Thumb}>
            <Slider.HiddenInput />
          </Slider.Thumb>
        </Slider.Control>
      </Slider.RootProvider>
    </>
  )
}

If you're using the RootProvider component, you don't need to use the Root component.

API Reference

Props

Root

PropDefaultType
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 rendered. Use when you don't need to control the value of the slider.

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 slider. Useful for composition.

invalid
boolean

Whether the slider is invalid

max100
number

The maximum value of the slider

min0
number

The minimum value of the slider

minStepsBetweenThumbs0
number

The minimum permitted steps between multiple thumbs. `minStepsBetweenThumbs` * `step` should reflect the gap between the thumbs. - `step: 1` and `minStepsBetweenThumbs: 10` => gap is `10` - `step: 10` and `minStepsBetweenThumbs: 2` => gap is `20`

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' | 'end'

The origin of the slider range. The track is filled from the origin to the thumb for single values. - "start": Useful when the value represents an absolute value - "center": Useful when the value represents an offset (relative) - "end": Useful when the value represents an offset from the end

readOnly
boolean

Whether the slider is read-only

step1
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 controlled value of the slider

CSS VariableDescription
--slider-thumb-widthThe thumb width of the slider
--slider-thumb-heightThe thumb height of the slider
--slider-thumb-transformThe thumb transform of the slider
--slider-range-startThe range start of the slider
--slider-range-endThe range end of the slider
--translate-xThe horizontal translation value
--translate-yThe vertical translation value
Data AttributeValue
[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

PropDefaultType
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 AttributeValue
[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

PropDefaultType
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 AttributeValue
[data-scope]slider
[data-part]dragging-indicator
[data-orientation]The orientation of the draggingindicator
[data-state]"open" | "closed"

HiddenInput

PropDefaultType
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

PropDefaultType
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 AttributeValue
[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

PropDefaultType
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 AttributeValue
[data-scope]slider
[data-part]marker-group
[data-orientation]The orientation of the markergroup

Marker

PropDefaultType
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 AttributeValue
[data-scope]slider
[data-part]marker
[data-orientation]The orientation of the marker
[data-value]The value of the item
[data-disabled]Present when disabled
[data-state]

Range

PropDefaultType
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 AttributeValue
[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

PropDefaultType
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

PropDefaultType
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 AttributeValue
[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

PropDefaultType
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 AttributeValue
[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

PropDefaultType
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 AttributeValue
[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

Context

These are the properties available when using Slider.Context, useSliderContext hook or useSlider hook.

API

PropertyType
value
number[]

The value of the slider.

dragging
boolean

Whether the slider is being dragged.

focused
boolean

Whether the slider is focused.

setValue
(value: number[]) => void

Function to set the value of the slider.

getThumbValue
(index: number) => number

Returns the value of the thumb at the given index.

setThumbValue
(index: number, value: number) => void

Sets the value of the thumb at the given index.

getValuePercent
(value: number) => number

Returns the percent of the thumb at the given index.

getPercentValue
(percent: number) => number

Returns the value of the thumb at the given percent.

getThumbPercent
(index: number) => number

Returns the percent of the thumb at the given index.

setThumbPercent
(index: number, percent: number) => void

Sets the percent of the thumb at the given index.

getThumbMin
(index: number) => number

Returns the min value of the thumb at the given index.

getThumbMax
(index: number) => number

Returns the max value of the thumb at the given index.

increment
(index: number) => void

Function to increment the value of the slider at the given index.

decrement
(index: number) => void

Function to decrement the value of the slider at the given index.

focus
VoidFunction

Function to focus the slider. This focuses the first thumb.

Accessibility

Complies with the Slider WAI-ARIA design pattern.

Keyboard Support

KeyDescription
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.

Prev page

Signature Pad

Next page

Splitter