When to use
- Set a value where the rough position matters more than the exact digit, such as a spend cap or an alert threshold.
- Pick a range with two thumbs, such as a price band, by passing an array of two values.
- Show the value as people drag, formatted as currency, a percentage or a unit, without wiring a readout yourself.
When not to use
- An exact number someone types, such as a quantity: use an Input with
type="number". - A few named steps, such as small, medium and large: use Segmented or a Radio Group.
- Adjusting a number inline by dragging its label: use Scrub Label.
Installation
pnpm dlx shadcn add https://eased.dev/r/slider.jsonnpx shadcn add https://eased.dev/r/slider.jsonyarn dlx shadcn add https://eased.dev/r/slider.jsonbunx --bun shadcn add https://eased.dev/r/slider.jsonThe command adds Slider, everything it builds on and Eased’s tokens to your project.
Install the dependencies
pnpm add @base-ui/react motionnpm install @base-ui/react motionyarn add @base-ui/react motionbun add @base-ui/react motionAdd the Eased pieces it builds on
Copy each item’s files the same way, or install them with the CLI:
Copy the source into your project
components/eased/slider/slider.tsxTSX "use client";import { Slider as BaseSlider } from "@base-ui/react/slider";import { useId, useState, type ReactNode } from "react";import { NumberRoll } from "../_primitives/number-roll/number-roll";export type SliderProps<V extends number | readonly number[]> = { /** The value (controlled). An array of two makes a range with two thumbs. */ value?: V; /** The initial value (uncontrolled). */ defaultValue?: V; /** Fires on every change while dragging or stepping. */ onValueChange?: (value: V) => void; /** Fires once when a drag ends or a key is released: save here. */ onValueCommitted?: (value: V) => void; /** Default 0. */ min?: number; /** Default 100. */ max?: number; /** Default 1. */ step?: number; /** Shift + arrow and Page keys move by this much. Default 10. */ largeStep?: number; /** Formats the readout and the value screen readers hear, e.g. `{ style: "currency", currency: "USD" }`. */ format?: Intl.NumberFormatOptions; /** Locale for `format`. Defaults to the runtime locale. */ locale?: Intl.LocalesArgument; /** The label above the track. Leave it out for a bare slider, and pass `aria-label`. */ label?: ReactNode; /** Show the value, rolling, on the label row. Default true when there is a label. */ showValue?: boolean; /** Minimum steps between a range's two thumbs. Default 0. */ minStepsBetweenValues?: number; name?: string; disabled?: boolean; "aria-label"?: string; className?: string;};/** * A slider on Base UI: drag, click the track, or use arrows, Shift + arrows, Page, Home and * End. Pass an array for a range. The thumb swells while held, and the readout's digits roll * when the value steps (keys, track clicks) and follow the finger exactly while dragging. */export function Slider<V extends number | readonly number[]>({ label, showValue, format, locale, onValueChange, onValueCommitted, "aria-label": ariaLabel, className = "", ...props}: SliderProps<V>) { const id = useId(); const [inner, setInner] = useState<number | readonly number[]>(props.value ?? props.defaultValue ?? props.min ?? 0); const [dragging, setDragging] = useState(false); const current = props.value ?? inner; const values = typeof current === "number" ? [current] : current; const withValue = showValue ?? label != null; return ( <BaseSlider.Root {...(props as BaseSlider.Root.Props<V>)} format={format} locale={locale} aria-labelledby={label != null ? `${id}-label` : undefined} onValueChange={(v, details) => { setDragging(details.reason === "drag"); setInner(v as number | readonly number[]); onValueChange?.(v as V); }} onValueCommitted={(v) => { setDragging(false); onValueCommitted?.(v as V); }} className={`group/slider flex min-w-0 flex-col gap-2 data-disabled:opacity-50 ${className}`} > {(label != null || withValue) && ( <div className="flex min-w-0 items-baseline justify-between gap-3"> {label != null && ( <span id={`${id}-label`} className="min-w-0 truncate text-ui font-medium text-text"> {label} </span> )} {withValue && ( <span className="ms-auto shrink-0 text-ui text-text-secondary tabular-nums" aria-hidden> {values.map((v, i) => ( <span key={i}> {i > 0 && <span className="px-1 text-text-muted">–</span>} <NumberRoll value={v} format={format} locale={locale} animated={!dragging} aria-hidden /> </span> ))} </span> )} </div> )} {/* A 20px control around a 4px track: the whole band is the hit target. */} <BaseSlider.Control className="relative flex h-5 w-full touch-none items-center select-none data-disabled:cursor-not-allowed"> <BaseSlider.Track className="relative h-1 w-full rounded-pill bg-surface-active inset-shadow-well"> <BaseSlider.Indicator className="rounded-pill bg-brand" /> {values.map((_, i) => ( <BaseSlider.Thumb key={i} index={values.length > 1 ? i : undefined} getAriaLabel={ariaLabel && values.length > 1 ? (n) => `${ariaLabel} ${n === 0 ? "minimum" : "maximum"}` : undefined} aria-label={values.length === 1 ? ariaLabel : undefined} className="group/thumb flex size-5 items-center justify-center rounded-pill outline-none [&:has(:focus-visible)>span]:shadow-[0_0_0_2px_var(--eased-bg),0_0_0_4px_var(--eased-ring)] data-disabled:cursor-not-allowed" > <span aria-hidden className="size-4 rounded-pill bg-surface-raised shadow-thumb [transition:scale_var(--eased-duration-spring-snappy)_var(--eased-spring-snappy),box-shadow_var(--eased-duration-focus)_var(--eased-ease-standard)] [@media(hover:hover)_and_(pointer:fine)]:group-hover/thumb:scale-110 group-data-dragging/thumb:scale-125 reduced:scale-100! dark:bg-text" /> </BaseSlider.Thumb> ))} </BaseSlider.Track> </BaseSlider.Control> </BaseSlider.Root> );}Keep the folder layout
The files import each other by relative path (
../lib/motion), so keep each one at the path shown, undercomponents/eased/.
Usage
import { useState } from "react";import { Slider } from "@/components/eased/slider/slider";export function SpendCap() { const [cap, setCap] = useState(400); return ( <Slider label="Monthly spend cap" value={cap} onValueChange={setCap} max={2000} step={50} largeStep={250} format={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} locale="en-US" /> );}Examples
Range
Pass an array of two values for two thumbs. Use minStepsBetweenValues to keep them apart, and aria-label to name each thumb ("Price per million tokens minimum" and "… maximum").
<Slider label="Model price range" defaultValue={[2, 15]} max={30} step={0.5} minStepsBetweenValues={2} format={{ style: "currency", currency: "USD" }} locale="en-US" aria-label="Price per million tokens"/>Save when the drag ends
Use onValueCommitted to save once when a drag ends or a key is released, instead of on every step.
<Slider label="Alert at" defaultValue={80} min={50} max={100} format={{ style: "unit", unit: "percent" }} onValueCommitted={saveThreshold} />Bare slider
Leave out label when the layout already names it, and pass aria-label. The readout hides with the label unless you set showValue.
<Slider aria-label="Volume" defaultValue={60} />API reference
Slider
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | readonly number[] | The value (controlled). Two values make a range. | |
defaultValue | number | readonly number[] | The initial value (uncontrolled). | |
onValueChange | (value) => void | Fires on every change while dragging or stepping. | |
onValueCommitted | (value) => void | Fires once when a drag ends or a key is released. | |
min | number | 0 | |
max | number | 100 | |
step | number | 1 | |
largeStep | number | 10 | How far Shift + arrow and Page Up / Page Down move. |
format | Intl.NumberFormatOptions | Formats the readout and the value screen readers hear. | |
locale | Intl.LocalesArgument | runtime locale | Locale for format. |
label | ReactNode | The label above the track. | |
showValue | boolean | true with a label | Shows the rolling readout on the label row. |
minStepsBetweenValues | number | 0 | Minimum steps between a range's two thumbs. |
name | string | Form field name. | |
disabled | boolean | Dims the slider to 50% and stops input. | |
aria-label | string | Names the thumb, or each thumb of a range with "minimum" and "maximum" added. | |
className | string | "" | Appended to the root's classes. |
Keyboard
| Key | Action |
|---|---|
Tab | Moves focus to the thumb, then to the second thumb of a range. |
← / → or ↑ / ↓ | Moves by step. |
Shift + arrow | Moves by largeStep. |
Page Up / Page Down | Moves by largeStep. |
Home / End | Moves to min / max. |
Accessibility
- Each thumb is a Base UI slider input with the value range and the formatted value, so screen readers hear "$400" rather than "400".
labelis tied to the slider througharia-labelledby;aria-labelnames the thumbs. A range adds "minimum" and "maximum" to each thumb's name.- The visible readout is hidden from screen readers, so the value isn't read twice.
- The track is 4px, but the 20px band around it is the hit target, and each thumb is a 20px target. Pressing anywhere on the band moves the nearest thumb there.
- The focus ring draws around the focused thumb.
Motion
The thumb swells to 1.1 on hover (pointer devices only) and to 1.25 while dragged, on the snappy spring. The readout's digits roll on Number Roll when the value steps from keys or a track press, and follow the finger exactly while dragging. Reduced motion: the thumb keeps its size and the digits change without rolling.
Notes for AI
Pick Slider when position matters more than precision, and pass format and locale so the readout and the announced value match. Save in onValueCommitted, not onValueChange, to avoid a request per pixel. For a range, pass an array and an aria-label so each thumb gets a distinct name.
Don't build your own value readout or label row: label and showValue already do it, with rolling digits. Don't format the value in a separate span; set format.
Responsive
The slider fills its container's width. The label truncates to one line and the readout keeps its size, so the label row never wraps on a narrow screen. Touch scrolling is off inside the 20px band only, so the page still scrolls around it.
Related components
- Scrubbable Number Label: drag a number's label to change it inline.
- Animated Number Counter: the rolling digits in the readout.
- Animated Text Input: type an exact number.