Skip to content
flyingsalmon

Slider

A slider picks a level from a short run of steps rather than a typed number, and a description says what the current step means.

Nightly budget

Up to $150 a night

Installation

npx shadcn@latest add @flyingsalmon/slider

Usage

import { useState } from 'react'

import { Slider } from '@/components/ui/slider'

export function SliderUsage() {
  const [nights, setNights] = useState(3)

  return (
    <Slider
      label="Nights"
      min={1}
      max={14}
      value={nights}
      description={`${nights} nights`}
      onValueChange={setNights}
    />
  )
}

Examples

Steps that mean something

The description is your words for the current step. It sits under the track and is what a screen reader announces, so a step reads as its meaning, not its index.

Pace

Two plans a day, long lunches

Disabled

Disabled dims the slider, its label, and its description, and takes the thumb out of the tab order. Say why in the description.

Nightly budget

Up to $200 a night, set by the organiser

In a form

Move the slider and save. The slider is controlled, name posts the value with the form, and the card shows the saved budget.

Lisbon long weekend

Brian Nguyen’s budget: up to $150 a night
Nightly budget

Up to $150 a night

Guidelines

When to use

  • To pick a level from a short run of steps, such as a pace or a budget band.
  • When the steps have a meaning you can write in a sentence.

When not to use

  • Use Number field when the traveller knows the exact number to enter, such as a budget of $1,200. A slider makes them hunt for it.
  • Use Toggle group for a few named options with no order, because a track implies one.
  • Use Date picker to pick a date.

Do and don’t

  • Do
    Keep to about seven steps, each a level the traveller could name.A dot marks every step, so a long run turns the track into a dotted line with no meaning.
  • Do
    Say under the track what the current step means, with its consequence: "$150 a day per person for 7 days, before flights".The description is the only place that says where the thumb is, and a figure the traveller can weigh turns a position into a decision.
  • Don’t
    Mark the ends of the track with their own figures.End labels make the traveller interpolate. The description already names the step the thumb is on.
  • Do
    Offer an exact entry beside the slider, one ghost button away, when the traveller may already know the figure.The slider answers "roughly". A traveller who knows their number should type it, not hunt for it on a track.

Accessibility

KeyDescription
TabMoves focus to the thumb. A disabled slider leaves the tab order.
ArrowLeftArrowDownMoves one step down and stops at the minimum.
ArrowRightArrowUpMoves one step up and stops at the maximum.
PageDownPageUpMoves ten steps down or up.
Shift+ArrowLeftShift+ArrowRightMoves ten steps down or up, as do Shift+ArrowDown and Shift+ArrowUp.
HomeEndJumps to the minimum or the maximum.

The thumb is the slider. It takes its name from the label and its aria-valuetext from the description. The dots and the fill are hidden from assistive technology, because the value text already says what they show. The focus ring appears on keyboard focus only. required marks the label; a slider always holds a value, so there is nothing for it to block. The accessibility page covers the rules every component follows.

API

Slider

Slider is controlled: it takes a value and reports the next one. It takes no other props.

PropTypeDefaultDescription
labelstringRequiredThe text above the track.
valuenumberRequiredThe current step.
onValueChange(value: number) => voidRequiredCalled with the next value as the thumb moves.
minnumber0The lowest value.
maxnumber100The highest value.
stepnumber1The distance between steps. A dot marks each one.
descriptionstring–What the current step means, shown under the track and announced as the value text.
requiredbooleanfalseMarks the label.
disabledbooleanfalseDims the slider and takes the thumb out of the tab order.
namestring–Posts the value under this name inside a form.
idstring–The id of the thumb. One is generated when omitted.
classNamestring–Styles the wrapper. The slider fills its container up to a fixed maximum width, so use this to narrow it further.

  • Number field

    For a number the traveller types exactly.
  • Toggle group

    For a few named options with no order.
  • Progress

    A track that shows a value instead of asking for one.
  • Fields

    The label and description behaviour fields share.