Slider

Free · MIT

A control for a value in a range, with one thumb or, when the value has two numbers, a range. Pass aria-label (or aria-labelledby) to name a single thumb, or thumbLabels for each thumb of a range. Arrow keys step, Page keys and Home/End jump. The thumb starts at min unless the app gives defaultValue; leave it there for a choice the person hasn't made, and show the value beside the slider, since a position alone isn't a number.

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0 and 2.2.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

Open the starter in StackBlitz

Opens the free starter app in StackBlitz, in your browser, on stackblitz.com. Slider isn’t added for you: run npx candor-ui add slider in its terminal. The starter’s agent needs an Anthropic API key to chat; without one it shows the components only.

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/slider

Brings in: locale, tokens, utils · npm: @base-ui/react@^1.9.0, lucide-react@^1.67.0

Usage

TSX · The example above

"use client"

import * as React from "react"
import { Slider } from "@/components/candor/ui/slider"
import { Label } from "@/components/candor/ui/label"

export default function Example() {
  const [budget, setBudget] = React.useState([20])
  const [range, setRange] = React.useState([10, 40])
  return (
    <div className="flex w-full max-w-sm flex-col gap-6">
      <div className="flex flex-col gap-2.5">
        <div className="flex items-center justify-between text-sm">
          <Label id="budget-label">Spending limit per run</Label>
          <span className="tabular-nums text-muted-foreground">${budget[0]}</span>
        </div>
        <Slider aria-labelledby="budget-label" min={0} max={100} step={5} value={budget} onValueChange={setBudget} />
      </div>
      <div className="flex flex-col gap-2.5">
        <div className="flex items-center justify-between text-sm">
          <span className="font-medium">Run time to keep</span>
          <span className="tabular-nums text-muted-foreground">
            {range[0]} to {range[1]} minutes
          </span>
        </div>
        <Slider thumbLabels={["Shortest run", "Longest run"]} min={0} max={60} value={range} onValueChange={setRange} />
      </div>
      <div className="flex flex-col gap-2.5">
        <span className="text-sm font-medium">Retention</span>
        <Slider aria-label="Retention in days" defaultValue={[30]} max={90} locked="Your plan keeps history for 30 days." />
      </div>
    </div>
  )
}

<Slider>

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes, merged with Candor's.
value	`number[] \| undefined`	—	The thumbs' values, when the app controls them: one number, or two for a range.
defaultValue	`number[] \| undefined`	—	The thumbs' values at first, when the slider keeps its own state.
onValueChange	`((value: number[]) => void) \| undefined`	—	Called with the thumbs' values as the person moves one.
onValueCommit	`((value: number[]) => void) \| undefined`	—	Called with the thumbs' values when the person lets go, or after a key press: the value to act on.
"aria-label"	`string \| undefined`	—	Names a single thumb.
"aria-labelledby"	`string \| undefined`	—	Names a single thumb by the id of the element that labels it.
locked	`string \| null \| undefined`	—	Why the slider can't be changed. With a reason it stays focusable but the pointer and arrow keys do nothing, it is marked `aria-disabled` and described by the reason, and the reason is printed under it. Without one the slider is normal. Use this rather than `disabled`, which takes the slider out of the tab order and says nothing. `null` or left out: unlocked.
thumbLabels	`string[] \| undefined`	—	A name for each thumb, in order (a range has two: "Lowest price", "Highest price"). A thumb without one takes `aria-label`; give them in the app's language.

Also takes the props of Omit<SliderPrimitive.Root.Props, "className" | "value" | "defaultValue" | "onValueChange" | "onValueCommitted">.

Motion

Moment	Family	What it does
tint	tint	The thumb's ring fades in when the pointer is over it and when it takes keyboard focus.

Set with --cd-motion-slider-<moment>-* in your brand file; the families are in the design reference.