Slider

A slider allows users to make selections from a range of values. Think of it as a custom <input type='range'/> with the ability to achieve custom styling and accessibility.

Quantity20

Properties

disabled

readOnly

origin

dir

Features

Supports centered origin (slider starting at center, instead of start position).
Fully managed keyboard navigation.
Supports touch or click on track to update value.
Supports Right-to-Left directionality.
Support for horizontal and vertical orientations.
Prevents text selection while dragging.

Installation

To use the slider machine in your project, run the following command in your command line:

npm install @zag-js/slider @zag-js/react
# or
yarn add @zag-js/slider @zag-js/react

npm install @zag-js/slider @zag-js/solid
# or
yarn add @zag-js/slider @zag-js/solid

npm install @zag-js/slider @zag-js/vue
# or
yarn add @zag-js/slider @zag-js/vue

This command will install the framework agnostic slider logic and the reactive utilities for your framework of choice.

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.

Usage

First, import the slider package into your project

import * as slider from "@zag-js/slider"

The slider package exports two key functions:

machine — The state machine logic for the slider widget as described in the WAI-ARIA spec.
connect — The function that translates the machine's state to JSX attributes and event handlers.

You'll need to provide a unique id to the useMachine hook. This is used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the slider machine in your project 🔥

import * as slider from "@zag-js/slider"
import { useMachine, normalizeProps } from "@zag-js/react"

export function Slider() {
  const [state, send] = useMachine(slider.machine({ id: "1", value: [0] }))

  const api = slider.connect(state, send, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <div>
        <label {...api.getLabelProps()}>Slider Label</label>
        <output {...api.getValueTextProps()}>{api.value.at(0)}</output>
      </div>
      <div {...api.getControlProps()}>
        <div {...api.getTrackProps()}>
          <div {...api.getRangeProps()} />
        </div>
        {api.value.map((_, index) => (
          <div key={index} {...api.getThumbProps({ index })}>
            <input {...api.getHiddenInputProps({ index })} />
          </div>
        ))}
      </div>
    </div>
  )
}

import * as slider from "@zag-js/slider"
import { normalizeProps, useMachine } from "@zag-js/solid"
import { createMemo, For, createUniqueId } from "solid-js"

export function Slider() {
  const [state, send] = useMachine(
    slider.machine({ id: createUniqueId(), value: [0] }),
  )

  const api = createMemo(() => slider.connect(state, send, normalizeProps))

  return (
    <div {...api().getRootProps()}>
      <div>
        <label {...api().getLabelProps()}>Slider Label</label>
        <output {...api().getValueTextProps()}>{api().value.at(0)}</output>
      </div>
      <div {...api().getControlProps()}>
        <div {...api().getTrackProps()}>
          <div {...api().getRangeProps()} />
        </div>
        <For each={api().value}>
          {(_, index) => (
            <div {...api().getThumbProps({ index: index() })}>
              <input {...api().getHiddenInputProps({ index: index() })} />
            </div>
          )}
        </For>
      </div>
    </div>
  )
}

<script setup>
import * as slider from "@zag-js/slider";
import { normalizeProps, useMachine } from "@zag-js/vue";
import { computed } from "vue";

const [state, send] = useMachine(slider.machine({ id: "1", value: [0] }));
const api = computed(() => slider.connect(state.value, send, normalizeProps));
</script>

<template>
  <div ref="ref" v-bind="api.getRootProps()">
    <div>
      <label v-bind="api.getLabelProps()">Slider Label</label>
      <output v-bind="api.getValueTextProps()">{{ api.value.at(0) }}</output>
    </div>
    <div v-bind="api.getControlProps()">
      <div v-bind="api.getTrackProps()">
        <div v-bind="api.getRangeProps()" />
      </div>
      <div
        v-for="(_, index) in api.value"
        :key="index"
        v-bind="api.getThumbProps({ index })"
      >
        <input v-bind="api.getHiddenInputProps({ index })" />
      </div>
    </div>
  </div>
</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

const [state, send] = useMachine(
  slider.machine({
    orientation: "vertical",
  }),
)

Setting the initial value

const [state, send] = useMachine(
  slider.machine({
    value: [30],
  }),
)

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

For example, to ask the user for a value between -10 and 10, you can use:

const [state, send] = useMachine(
  slider.machine({
    min: -10,
    max: 10,
  }),
)

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:

const [state, send] = useMachine(
  slider.machine({
    min: 5,
    max: 10,
    step: 0.01,
  }),
)

Listening for changes

When the slider value changes, the onValueChange and onValueChangeEnd callbacks are invoked. You can use this to setup custom behaviors in your app.

const [state, send] = useMachine(
  slider.machine({
    onValueChange(details) {
      console.log("value is changing to:", details)
    },
    onValueChangeEnd(details) {
      console.log("value has changed to:", details)
    },
  }),
)

Changing the start position

By default, the slider's "zero position" is usually at the start position (left in LTR and right in RTL).

In scenarios where the value represents an offset (or relative value), it might be useful to change the "zero position" to center. To do this, pass the origin context property to center.

const [state, send] = useMachine(
  slider.machine({
    origin: "center",
  }),
)

Changing the thumb alignment

By default, the thumb is aligned to the start of the track. Set the thumbAlignment context property to contain or center.

center: the thumb will extend beyond the bounds of the slider track.
contain: the thumb will be contained within the bounds of the track.

const [state, send] = useMachine(
  slider.machine({
    thumbAlignment: "center",
  }),
)

If you use contain alignment, you might need to set the thumb size to prevent any flickering.

const [state, send] = useMachine(
  slider.machine({
    thumbAlignment: "contain",
    thumbSize: { width: 20, height: 20 },
  }),
)

Usage within forms

To use slider within forms, use the exposed inputProps from the connect function and ensure you pass name value to the machine's context. It will render a hidden input and ensure the value changes get propagated to the form correctly.

const [state, send] = useMachine(
  slider.machine({
    name: "quantity",
  }),
)

RTL Support

The slider has built-in support for RTL alignment and interaction. In the RTL mode, operations are performed from right to left, meaning, the left arrow key will increment and the right arrow key will decrement.

To enable RTL support, pass the dir: rtl context property

const [state, send] = useMachine(
  slider.machine({
    dir: "rtl",
  }),
)

While we take care of the interactions in RTL mode, you'll have to ensure you apply the correct CSS styles to flip the layout.

Using slider marks

To show marks or ticks along the slider track, use the exposed api.getMarkerProps() method to position the slider marks relative to the track.

//...
<div>
  <div {...api.getControlProps()}>
    <div {...api.getTrackProps()}>
      <div {...api.getRangeProps()} />
    </div>
    {api.value.map((_, index) => (
      <div key={index} {...api.getThumbProps({ index })}>
        <input {...api.getHiddenInputProps({ index })} />
      </div>
    ))}
  </div>
  <div {...api.getMarkerGroupProps()}>
    <span {...api.getMarkerProps({ value: 10 })}>|</span>
    <span {...api.getMarkerProps({ value: 30 })}>|</span>
    <span {...api.getMarkerProps({ value: 90 })}>|</span>
  </div>
</div>
//...

//...
<div>
  <div {...api().getControlProps()}>
    <div {...api().getTrackProps()}>
      <div {...api().getRangeProps()} />
    </div>
    <div {...api().getThumbProps({ index: 0 })}>
      <input {...api().getHiddenInputProps({ index: 0 })} />
    </div>
  </div>
  <div {...api().getMarkerGroupProps()}>
    <span {...api().getMarkerProps({ value: 10 })}>|</span>
    <span {...api().getMarkerProps({ value: 30 })}>|</span>
    <span {...api().getMarkerProps({ value: 90 })}>|</span>
  </div>
</div>
//...

//...

<div>
  <div v-bind="api.getControlProps()">
    <div v-bind="api.getTrackProps()">
      <div v-bind="api.getRangeProps()" />
    </div>
    <div v-bind="api.getThumbProps({ index: 0 })">
      <input v-bind="api.getHiddenInputProps({ index: 0 })" />
    </div>
  </div>
  <div v-bind="api.getMarkerGroupProps()">
    <span v-bind="api.getMarkerProps({ value: 10 })">|</span>
    <span v-bind="api.getMarkerProps({ value: 30 })">|</span>
    <span v-bind="api.getMarkerProps({ value: 90 })">|</span>
  </div>
</div>
//...

Styling guide

Earlier, we mentioned that each slider part has a data-part attribute added to them to select and style them in the DOM.

Focused State

When the slider thumb is focused, the data-focus attribute is added to the root, control, thumb and label parts.

[data-part="root"][data-focus] {
  /* styles for root focus state */
}

[data-part="thumb"]:focus {
  /* styles for thumb focus state */
}

[data-part="control"][data-focus] {
  /* styles for control focus state */
}

[data-part="track"][data-focus] {
  /* styles for track focus state */
}

[data-part="range"][data-focus] {
  /* styles for range focus state */
}

Disabled State

When the slider is disabled, the data-disabled attribute is added to the root, label, control and thumb.

[data-part="root"][data-disabled] {
  /* styles for root disabled state */
}

[data-part="label"][data-disabled] {
  /* styles for label disabled state */
}

[data-part="control"][data-disabled] {
  /* styles for control disabled state */
}

[data-part="value-text"][data-disabled] {
  /* styles for output disabled state */
}

[data-part="thumb"][data-disabled] {
  /* styles for thumb disabled state */
}

[data-part="range"][data-disabled] {
  /* styles for thumb disabled state */
}

Invalid State

When the slider is invalid, the data-invalid attribute is added to the root, track, range, label, and thumb parts.

[data-part="root"][data-invalid] {
  /* styles for root invalid state */
}

[data-part="label"][data-invalid] {
  /* styles for label invalid state */
}

[data-part="control"][data-invalid] {
  /* styles for control invalid state */
}

[data-part="valueText"][data-invalid] {
  /* styles for output invalid state */
}

[data-part="thumb"][data-invalid] {
  /* styles for thumb invalid state */
}

[data-part="range"][data-invalid] {
  /* styles for range invalid state */
}

Orientation

[data-part="root"][data-orientation="(horizontal|vertical)"] {
  /* styles for horizontal or vertical  */
}

[data-part="thumb"][data-orientation="(horizontal|vertical)"] {
  /* styles for horizontal or vertical  */
}

[data-part="track"][data-orientation="(horizontal|vertical)"] {
  /* styles for horizontal or vertical  */
}

Styling the markers

[data-part="marker"][data-state="(at|under|over)-value"] {
  /* styles for when the value exceeds the marker's value */
}

Methods and Properties

Machine Context

The slider machine exposes the following context properties:

idsPartial<{ 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.

aria-labelstring[]The aria-label of each slider thumb. Useful for providing an accessible name to the slider

aria-labelledbystring[]The `id` of the elements that labels each slider thumb. Useful for providing an accessible name to the slider

namestringThe name associated with each slider thumb (when used in a form)

formstringThe associate form of the underlying input element.

valuenumber[]The value of the range slider

disabledbooleanWhether the slider is disabled

readOnlybooleanWhether the slider is read-only

invalidbooleanWhether the slider is invalid

onValueChange(details: ValueChangeDetails) => voidFunction invoked when the value of the slider changes

onValueChangeEnd(details: ValueChangeDetails) => voidFunction invoked when the slider value change is done

onFocusChange(details: FocusChangeDetails) => voidFunction invoked when the slider's focused index changes

getAriaValueText(details: ValueTextDetails) => stringFunction that returns a human readable value for the slider thumb

minnumberThe minimum value of the slider

maxnumberThe maximum value of the slider

stepnumberThe step value of the slider

minStepsBetweenThumbsnumberThe minimum permitted steps between multiple thumbs.

orientation"vertical" | "horizontal"The orientation of the slider

origin"start" | "center"The origin of the slider range - "start": Useful when the value represents an absolute value - "center": Useful when the value represents an offset (relative)

thumbAlignment"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

dir"ltr" | "rtl"The document's text/writing direction.

idstringThe unique identifier of the machine.

getRootNode() => ShadowRoot | Node | DocumentA root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

Machine API

The slider api exposes the following methods:

valuenumber[]The value of the slider.

draggingbooleanWhether the slider is being dragged.

focusedbooleanWhether the slider is focused.

setValue(value: number[]) => voidFunction to set the value of the slider.

getThumbValue(index: number) => numberReturns the value of the thumb at the given index.

setThumbValue(index: number, value: number) => voidSets the value of the thumb at the given index.

getValuePercent(value: number) => numberReturns the percent of the thumb at the given index.

getPercentValue(percent: number) => numberReturns the value of the thumb at the given percent.

getThumbPercent(index: number) => numberReturns the percent of the thumb at the given index.

setThumbPercent(index: number, percent: number) => voidSets the percent of the thumb at the given index.

getThumbMin(index: number) => numberReturns the min value of the thumb at the given index.

getThumbMax(index: number) => numberReturns the max value of the thumb at the given index.

increment(index: number) => voidFunction to increment the value of the slider at the given index.

decrement(index: number) => voidFunction to decrement the value of the slider at the given index.

focus() => voidFunction to focus the slider. This focuses the first thumb.

Data Attributes

Label

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

Root

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

ValueText

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

Track

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

Thumb

data-scope

slider

data-part

thumb

data-index

The index of the item

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

Range

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

Control

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

MarkerGroup

data-scope

slider

data-part

marker-group

data-orientation

The orientation of the markergroup

Marker

data-scope

slider

data-part

marker

data-orientation

The orientation of the marker

data-disabled

Present when disabled

Accessibility

Adheres to the Slider WAI-ARIA design pattern.

Keyboard Interactions

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.

Edit this page on GitHub

Slider

Anatomy

Usage

Changing the orientation

Setting the initial value

Specifying the minimum and maximum

Setting the value's granularity

Listening for changes

Changing the start position

Changing the thumb alignment

Usage within forms

RTL Support

Using slider marks

Styling guide

Focused State

Disabled State

Invalid State

Orientation

Styling the markers

Methods and Properties

Machine Context

Machine API

Data Attributes

Accessibility

Keyboard Interactions

On this page