React Slider component

Preview

<div style={{ width: '300px' }}>
  <Slider label="Volume" defaultValue={50} />
</div>

Usage

Use when

Any value along a range, where roughly right is good enough
Volume, brightness, opacity
Price and range filters
The effect is visible as the user drags

Avoid when

An exact number matters (use Input type="number")
A handful of fixed choices (use RadioGroup or Select)
On or off (use Switch)
A value the user cannot change here (show it as text, or set readOnly when it sits among editable fields)

Implementation notes

Label what the track controls
Turn on showValue whenever the number matters, and format it with Intl options instead of a string suffix
Set min and max to the real limits, not 0-100 by habit
Pick a step the user can actually land on
Give each thumb of a range its own name with getAriaLabel

Installation

pnpm add @usefragments/ui

Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Examples

With Value Display

showValue prints the number opposite the label.

<div style={{ width: '300px' }}>
  <Slider
    label="Opacity"
    defaultValue={0.75}
    max={1}
    step={0.05}

Custom Range

min, max and step bound the track to real-world units.

<div style={{ width: '300px', display: 'flex', flexDirection: 'column', gap: '16px' }}>
  <Slider
    label="Temperature"
    min={60}
    max={80}
    defaultValue={72}

Range

Two thumbs choose a span; each thumb has its own name.

<div style={{ width: '300px' }}>
  <Slider
    label="Price"
    defaultValue={[20, 80]}
    getAriaLabel={(index) => (index === 0 ? 'Minimum price' : 'Maximum price')}
    format={{ style: 'currency', currency: 'USD', maximumFractionDigits: 0 }}

Controlled

The parent owns the value and can react to every move.

<ControlledSliderDemo />

Drag Value Bubble

The number floats above the thumb only while dragging.

<div style={{ width: '300px' }}>
  <Slider label="Mix" defaultValue={40} showValueOnDrag />
</div>

With Helper Text

A line below the track explains the trade-off.

<div style={{ width: '300px' }}>
  <Slider
    label="Quality"
    defaultValue={80}
    showValue
    helperText="Higher quality increases file size"

Invalid

The track takes the danger edge; the message has an icon and words.

<div style={{ width: '300px' }}>
  <Slider
    label="Budget"
    defaultValue={90}
    showValue
    invalid

Read-only

A dashed track; the thumb does not move.

<div style={{ width: '300px' }}>
  <Slider label="Seats" defaultValue={12} max={20} showValue readOnly />
</div>

Disabled

Dimmed; the thumb will not move.

<div style={{ width: '300px' }}>
  <Slider
    label="Locked Setting"
    defaultValue={30}
    showValue
    disabled

API reference

Component props
Prop	Type	Default	Description
`aria-describedby`	`string \| undefined`	Not set	Accessible described-by relationship
`aria-label`	`string \| undefined`	Not set	Accessible label when the visible label is omitted
`aria-labelledby`	`string \| undefined`	Not set	Accessible labelled-by relationship
`defaultValue`	`Value \| undefined`	Not set	Default value for uncontrolled usage
`disabled`	`boolean \| undefined`	`false`	Disable the slider
`errorMessage`	`React.ReactNode`	Not set	Message shown under the slider while invalid is true
`form`	`string \| undefined`	Not set	ID of the form that owns the hidden input
`format`	`Intl.NumberFormatOptions \| undefined`	Not set	Number formatting for the shown value, the bubble and the announced value
`getAriaLabel`	`((index: number) => string) \| undefined`	Not set	Accessible name for each thumb of a range, by index: (index: number) => string
`helperText`	`string \| undefined`	Not set	Helper text shown below the slider
`invalid`	`boolean \| undefined`	`false`	Whether the value fails validation. The track takes the danger edge and errorMessage shows under it with an icon.
`label`	`string \| undefined`	Not set	Visible label text. A slider needs a label, aria-label or aria-labelledby; there is no fallback name.
`largeStep`	`number \| undefined`	Not set	Larger step for Page Up/Page Down and shift-arrow keys
`locale`	`Intl.LocalesArgument`	Not set	Locale for format; defaults to the runtime locale
`max`	`number \| undefined`	`100`	Maximum value
`min`	`number \| undefined`	`0`	Minimum value
`name`	`string \| undefined`	Not set	Name of the hidden input for form submission
`onValueChange`	`((value: SliderOutput<Value>) => void) \| undefined`	Not set	Called with the new value while the user moves a thumb: (value: number \| number[]) => void
`onValueCommitted`	`((value: SliderOutput<Value>) => void) \| undefined`	Not set	Called with the value when the user finishes an interaction
`readOnly`	`boolean \| undefined`	`false`	Show the value without letting the user change it
`showValue`	`boolean \| undefined`	`false`	Show the formatted value beside the label
`showValueOnDrag`	`boolean \| undefined`	`false`	Show the formatted value in a bubble above the thumb while dragging
`size`	`"xs" \| "sm" \| "md" \| "lg" \| undefinedxssmmdlg`	`"md"`	Height of the control strip, so a slider lines up with fields of the same size. The track and thumb keep one size.
`step`	`number \| undefined`	`1`	Step interval
`thumbAlignment`	`"center" \| "edge" \| "edge-client-only" \| undefinedcenteredgeedge-client-only`	Not set	How the thumb aligns at the minimum and maximum edges
`value`	`Value \| undefined`	Not set	Controlled value: a number, or an array for a range (one thumb per value)
`id`	`string \| undefined`	Not set	ID of the slider root

Accessibility

The visible label names every thumb; a range names each thumb with getAriaLabel
Arrow keys move the thumb; Page Up and Page Down move by largeStep
The formatted value is announced
An invalid slider shows an icon and words, wired to the thumb with aria-describedby
A read-only slider says so with aria-readonly

Standards references

InputalternativeUse Input for precise numeric entry
ProgresssiblingSimilar visual, but Progress is read-only

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.