Slider

Playground

import { Slider, SliderTrack, SliderRange, SliderThumb } from "@/components/ui/slider";
<Slider size="md" defaultValue={[40]}>  <SliderTrack>    <SliderRange />  </SliderTrack>  <SliderThumb aria-label="Volume" /></Slider>

import { Slider } from "@primitiv-ui/react";
<Slider.Root defaultValue={[40]}>  <Slider.Track>    <Slider.Range />  </Slider.Track>  <Slider.Thumb aria-label="Volume" /></Slider.Root>

Installation

npx primitiv add slider

pnpm dlx primitiv add slider

yarn dlx primitiv add slider

bunx primitiv add slider

import { Slider } from "@/components/ui/slider";

Anatomy

Four parts, and you compose all of them — in both modes, unlike the choice controls whose copied file renders its own indicator. The Root owns the value and the keyboard; Track is the full-length rail, Range the filled portion of it, and each Thumb is one focusable handle. The number of thumbs is the number of Thumb children — that is the whole API for going from a single value to a range.

<Slider defaultValue={[40]}>  <SliderTrack>    <SliderRange />  </SliderTrack>  <SliderThumb /></Slider>

<Slider.Root defaultValue={[40]}>  <Slider.Track>    <Slider.Range />  </Slider.Track>  <Slider.Thumb /></Slider.Root>

<Slider defaultValue={[20, 60]}>  <SliderTrack>    <SliderRange />  </SliderTrack>  <SliderThumb aria-label="Minimum" />  <SliderThumb aria-label="Maximum" /></Slider>

<Slider.Root defaultValue={[20, 60]}>  <Slider.Track>    <Slider.Range />  </Slider.Track>  <Slider.Thumb aria-label="Minimum" />  <Slider.Thumb aria-label="Maximum" /></Slider.Root>

Props

Generated from source — headless rows from each *Props type’s JSDoc, styled rows from contract.json. Never hand-maintained.

Slider.Root

Extends HTMLSpanElement — every native attribute of that element is accepted and forwarded.

Slider.Track

Extends HTMLSpanElement — every native attribute of that element is accepted and forwarded.

Slider.Range

Extends HTMLSpanElement — every native attribute of that element is accepted and forwarded.

Slider.Thumb

Extends HTMLSpanElement — every native attribute of that element is accepted and forwarded.

Styling contract

11 CSS custom properties on .primitiv-slider — mode-agnostic. These names are the stable surface; the values are not.

Keyboard

Each thumb is independently focusable and carries the full keymap, so a range slider is two tab stops. Arrow direction follows orientation, dir and inverted together — in a right-to-left, inverted vertical slider, “increase” is still the direction that looks like increase.

Data attributes

Emitted automatically by the headless primitive — style against these rather than adding your own state classes. Grouped by the part that emits them, since most are emitted by more than one.

Accessibility

• Every thumb is a role="slider" carrying aria-valuenow, aria-valuemin and aria-valuemax, so the position is announced without any work from you. What is not automatic is the name — the control announces "40" and nothing else unless you label it.
• Label the Thumb, never the Root. The Root renders a plain <span> with no role, so an aria-label on it is attached to nothing and announced nowhere — a silent failure, since the slider still looks and behaves correctly. Slider.Root's own JSDoc example shows aria-label on the Root, which is misleading; the Thumb's example has it right.
• A Field label does not reach the thumb. Only Input, Textarea and Select read FieldContext, and a <label htmlFor> cannot associate with a <span role="slider"> anyway — so Field.Label beside a slider renders a reference to an id nothing claims. Give the label an id and point aria-labelledby at it from each thumb.
• On a range, label the thumbs separately. Two thumbs sharing one label are announced identically, which makes it impossible to tell by ear which end you are on — aria-label="Minimum" and "Maximum" is the smallest fix.
• A slider is a poor fit for a value that has to be exact. Pair it with a number input when precision matters, and keep the two in sync — the slider for the rough gesture, the field for the specific figure.
• onValueCommit is the accessible place for expensive work, not a debounce. A keyboard user pressing an arrow key commits immediately on that press, so a debounce keyed to pointer movement makes the keyboard path feel broken while the mouse path feels fine.
• disabled removes the thumbs from the tab order. If the range is unavailable for a reason the user could act on, explain it in nearby text — a disabled slider announces nothing about why.
• The arrow keys follow orientation, dir and inverted, so "increase" always matches the direction the thumb visibly moves. Do not re-map the keys yourself to compensate for an inverted track; set inverted and let the component handle both.

Examples

Every example below reacts to the density control. Currently showing Styled mode.

import { useState } from "react";import { Slider, SliderTrack, SliderRange, SliderThumb } from "@/components/ui/slider";
const [value, setValue] = useState([20, 60]);
<Slider value={value} onValueChange={setValue} minStepsBetweenThumbs={10}>  <SliderTrack>    <SliderRange />  </SliderTrack>  <SliderThumb aria-label="Minimum" />  <SliderThumb aria-label="Maximum" /></Slider>

import { useState } from "react";import { Slider } from "@primitiv-ui/react";
const [value, setValue] = useState([20, 60]);
<Slider.Root value={value} onValueChange={setValue} minStepsBetweenThumbs={10}>  <Slider.Track>    <Slider.Range />  </Slider.Track>  <Slider.Thumb aria-label="Minimum" />  <Slider.Thumb aria-label="Maximum" /></Slider.Root>

import { useState } from "react";import { Slider, SliderTrack, SliderRange, SliderThumb } from "@/components/ui/slider";
// keep the UI in sync on every step...// ...but only persist the settled value<Slider defaultValue={[40]} onValueChange={setPreview} onValueCommit={save}>  <SliderTrack>    <SliderRange />  </SliderTrack>  <SliderThumb /></Slider>

import { useState } from "react";import { Slider } from "@primitiv-ui/react";
// keep the UI in sync on every step...// ...but only persist the settled value<Slider.Root defaultValue={[40]} onValueChange={setPreview} onValueCommit={save}>  <Slider.Track>    <Slider.Range />  </Slider.Track>  <Slider.Thumb /></Slider.Root>

import { Slider, SliderTrack, SliderRange, SliderThumb } from "@/components/ui/slider";
<Slider min={0} max={1000} step={50} defaultValue={[400]}>  <SliderTrack>    <SliderRange />  </SliderTrack>  <SliderThumb aria-label="Budget" /></Slider>

import { Slider } from "@primitiv-ui/react";
<Slider.Root min={0} max={1000} step={50} defaultValue={[400]}>  <Slider.Track>    <Slider.Range />  </Slider.Track>  <Slider.Thumb aria-label="Budget" /></Slider.Root>

import { Slider, SliderTrack, SliderRange, SliderThumb } from "@/components/ui/slider";
// a visible label needs an id, and the THUMB points at it<span id="volume-label">Volume</span><Slider defaultValue={[40]}>  <SliderTrack>    <SliderRange />  </SliderTrack>  <SliderThumb aria-labelledby="volume-label" /></Slider>
// no visible label? name the thumb directly<SliderThumb aria-label="Volume" />

import { Slider } from "@primitiv-ui/react";
// a visible label needs an id, and the THUMB points at it<span id="volume-label">Volume</span><Slider.Root defaultValue={[40]}>  <Slider.Track>    <Slider.Range />  </Slider.Track>  <Slider.Thumb aria-labelledby="volume-label" /></Slider.Root>
// no visible label? name the thumb directly<Slider.Thumb aria-label="Volume" />

import { Slider, SliderTrack, SliderRange, SliderThumb } from "@/components/ui/slider";
<Slider disabled defaultValue={[40]}>  <SliderTrack>    <SliderRange />  </SliderTrack>  <SliderThumb aria-label="Volume" /></Slider>

import { Slider } from "@primitiv-ui/react";
<Slider.Root disabled defaultValue={[40]}>  <Slider.Track>    <Slider.Range />  </Slider.Track>  <Slider.Thumb aria-label="Volume" /></Slider.Root>