Slider

A value or a range picked on a scale, with the keyboard or by dragging.

A slider picks a value where the position on a scale matters more than the exact number, such as a share or a range of ages. With two values it picks a range. When the exact number matters, pair it with text that shows the value, or use a NumberField.

One value, a range and disabledClient

Full source examples/ui/slider.tsx

// apps/docs/examples/ui/slider.tsx'use client';
import {useState} from 'react';
import {  Field,  FieldDescription,  FieldLabel,} from '@workspace/active-ui/components/primitives/field';import {Slider} from '@workspace/active-ui/components/primitives/slider';
/** * A value picked on a scale: one thumb, a range with two thumbs and a step, * and a disabled slider. The value is an array, one number per thumb; the * current value is shown as text, because a slider alone does not tell the * reader the exact number. */export default function SliderExample() {  const [share, setShare] = useState([40]);  const [range, setRange] = useState([25, 65]);  return (    <div className="grid w-full max-w-md gap-8">      <Field>        <FieldLabel id="slider-share-label">Equity share</FieldLabel>        <Slider          value={share}          onValueChange={(value) => setShare(value as number[])}          aria-labelledby="slider-share-label"        />        <FieldDescription>{share[0]}% of the contributions</FieldDescription>      </Field>      <Field>        <FieldLabel id="slider-age-label">Age range</FieldLabel>        <Slider          value={range}          min={18}          max={67}          step={1}          onValueChange={(value) => setRange(value as number[])}          aria-labelledby="slider-age-label"        />        <FieldDescription>          From {range[0]} to {range[1]} years        </FieldDescription>      </Field>      {/* The label keeps full contrast: it names a control that is not          associated with it by `for`, so it is not exempt as disabled text. */}      <Field>        <FieldLabel id="slider-fixed-label">Employer share (fixed)</FieldLabel>        <Slider          defaultValue={[50]}          disabled          aria-labelledby="slider-fixed-label"        />      </Field>    </div>  );}

Usage#

TSX

import {Slider} from '@workspace/active-ui/components/primitives/slider';
<Slider  value={share}  onValueChange={(value) => setShare(value as number[])}  aria-labelledby="share-label"/>;

Values and thumbs#

One thumb per value. A number (40) or an array of one ([40]) gives one thumb; an array of two ([25, 65]) a range. onValueChange reports the value in the shape you passed.
Without value or defaultValue it renders two thumbs, at min and max: a range.
min (default 0), max (default 100) and step (default 1) set the scale.
onValueChange reports while the reader drags; onValueCommitted once, when they let go. Use the second for work that should not run on every step, such as a request.

What your application provides#

A label: aria-labelledby pointing at visible text, or aria-label. Both reach the input of every thumb; a range has one name for both thumbs.
The value as text, when the reader needs the number. The slider announces it to assistive technology (aria-valuenow), but shows no number itself.
locale, and format for a value that is more than a plain number (a percentage, a currency). Base UI formats the announced value with Intl.NumberFormat; without locale it uses the browser's language, not the one your application presents.

Accessibility and keyboard#

Each thumb is a tab stop. The arrow keys move it by step; Page Up and Page Down by a larger step (largeStep, default 10); Home and End to min and max.
Each thumb is a role="slider" input with its minimum, maximum and value.
When two thumbs meet while dragging, the one you drag pushes the other along (thumbCollisionBehavior, default push; swap and none are the alternatives).

API#

Import from @workspace/active-ui/components/primitives/slider

All props come from the Base UI part this component is built on.

Props

value

Type: number | readonly number[]

The value of the slider. For range sliders, provide an array with one value per thumb.

defaultValue

Type: number | readonly number[]

The uncontrolled value of the slider when it's initially rendered.

To render a controlled slider, use the value prop instead.

disabled

Type: boolean
Default: false

Whether the slider should ignore user interaction.

form

Type: string

Identifies the form that owns the slider inputs. Useful when the slider is rendered outside the form.

format

Type: Intl.NumberFormatOptions

Options to format the value.

largeStep

Type: number
Default: 10

The granularity with which the slider can step through values when using Page Up/Page Down or Shift + Arrow Up/Arrow Down.

locale

Type: Intl.LocalesArgument

The locale used by Intl.NumberFormat when formatting the value. Defaults to the user's runtime locale.

max

Type: number
Default: 100

The maximum allowed value of the slider. Should not be equal to min.

min

Type: number
Default: 0

The minimum allowed value of the slider. Should not be equal to max.

minStepsBetweenValues

Type: number
Default: 0

The minimum steps between values in a range slider.

name

Type: string

Identifies the field when a form is submitted.

orientation

Type: Orientation
Default: 'horizontal'

The component orientation.

step

Type: number
Default: 1

The granularity with which the slider can step through values. (A "discrete" slider.) The min prop serves as the origin for the valid values. We recommend (max - min) to be evenly divisible by the step.

thumbAlignment

Type: "center""edge""edge-client-only"
Default: 'center'

How the thumb(s) are aligned relative to Slider.Control when the value is at min or max:

center: The center of the thumb is aligned with the control edge
edge: The thumb is inset within the control such that its edge is aligned with the control edge
edge-client-only: Same as edge but renders after React hydration on the client, reducing bundle size in return

thumbCollisionBehavior

Type: "none""push""swap"
Default: 'push'

Controls how thumbs behave when they collide during pointer interactions.

'push' (default): Thumbs push each other without restoring their previous positions when dragged back.
'swap': Thumbs swap places when dragged past each other.
'none': Thumbs cannot move past each other; excess movement is ignored.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Events

Called by the component when something happens.

onValueChange

Type: (value, eventDetails) => void

Callback function that is fired when the slider's value changed. Receives the new value as the first argument; the originating event is available as eventDetails.event. The value is also reflected on eventDetails.event.target.value for form integration.

The eventDetails.reason indicates what triggered the change:

'input-change' when the hidden range input emits a change event (for example, via form integration)
'track-press' when the control track is pressed
'drag' while dragging a thumb
'keyboard' for keyboard input
'none' when the change is triggered without a specific interaction

onValueCommitted

Type: (value, eventDetails) => void

Callback function that is fired when a value change is committed. Does not fire if the value did not change, or if the change was canceled. Warning: This is a generic event, not a change event.

The eventDetails.reason indicates what triggered the commit:

'drag' while dragging a thumb
'track-press' when the control track is pressed
'keyboard' for keyboard input
'input-change' when the hidden range input emits a change event (for example, via form integration)
'none' when the commit occurs without a specific interaction

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

Based on shadcn/ui

This page adapts the Slider documentation of shadcn/ui (MIT licence) to this package; see Third-party notices.