# Slider

Picks a single value or a range by dragging.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Slider.tsx)

## Overview

Slider renders a horizontal control for a single value or a range, with one `Slider.Thumb` per value.

## Examples

### Basic

```tsx
import { Slider, style } from '@tempoxyz/ds'
import { useState } from 'react'

export const fill = true
export function Demo() {
  const [amount, setAmount] = useState(40)

  return (
    <Slider.Root aria-label="Amount" onValueChange={setAmount} value={amount} {...styles.root()}>
      <div {...styles.header()}>
        <span>Amount</span>
        <Slider.Value />
      </div>
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb aria-label="Amount" />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  )
}

namespace styles {
  export const header = style({
    display: 'flex',
    justifyContent: 'space-between',
    marginBottom: '8',
  })

  export const root = style({ maxWidth: '360px !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Slider/Basic.tsx)

### Range

Pass an array to `defaultValue` or `value` and add one `Slider.Thumb` per value, each with its `index`.

```tsx
import { Slider, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Slider.Root aria-label="Range" defaultValue={[20, 70]} {...styles.root()}>
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb aria-label="Minimum" index={0} />
          <Slider.Thumb aria-label="Maximum" index={1} />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  )
}

namespace styles {
  export const root = style({ maxWidth: '360px !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Slider/Range.tsx)

### Disabled

Set `disabled` to lock the slider at its current value.

```tsx
import { Slider, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Slider.Root aria-label="Locked" defaultValue={60} disabled {...styles.root()}>
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb aria-label="Locked" />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  )
}

namespace styles {
  export const root = style({ maxWidth: '360px !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Slider/Disabled.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Slider } from '@tempoxyz/ds'

<Slider.Root>
  <Slider.Value />
  <Slider.Control>
    <Slider.Track>
      <Slider.Indicator />
      <Slider.Thumb />
    </Slider.Track>
  </Slider.Control>
</Slider.Root>
```

## Guidelines

### When to Use

* Set a value where position matters more than the exact number, such as a benchmark's target load.
* Pick a range with two thumbs, such as the block heights on a chart.
* Preview a setting live, such as a chart's moving-average window.

### When Not to Use

* Use [AmountInput](/docs/components/amount-input) for amounts and [NumberField](/docs/components/number-field) for exact counts.
* Use [ChoiceGroup](/docs/components/choice-group) for a few presets, such as 25%, 50%, and Max.
* Use [Progress](/docs/components/progress) or [Gauge](/docs/components/gauge) for a value that people cannot change.

### Always Show the Value

**Do:** Show the current value and its unit beside the label.

```tsx
/**
 * Do example for "Always Show the Value" on the Slider page.
 * Show the current value and its unit beside the label.
 * @module
 */
import { Slider, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Slider.Root
      aria-labelledby="guideline-target-load"
      defaultValue={4000}
      max={10000}
      step={500}
      {...styles.root()}
    >
      <div {...styles.header()}>
        <span id="guideline-target-load">Target load</span>
        <span>
          <Slider.Value /> TPS
        </span>
      </div>
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  )
}

namespace styles {
  export const header = style({
    display: 'flex',
    justifyContent: 'space-between',
    marginBottom: '8',
    typography: 'body.b2',
  })

  export const root = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

**Don't:** Show a slider without its value.

```tsx
/** Don't example for "Always Show the Value" on the Slider page. Don't show a slider without its value. @module */
import { Slider, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Slider.Root
      aria-labelledby="guideline-target-load-hidden"
      defaultValue={4000}
      max={10000}
      step={500}
      {...styles.root()}
    >
      <div {...styles.header()}>
        <span id="guideline-target-load-hidden">Target load</span>
      </div>
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  )
}

namespace styles {
  export const header = style({ marginBottom: '8', typography: 'body.b2' })

  export const root = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

`Slider.Value` renders an `<output>` with tabular figures, so the label does not shift. Format it with `format` and `locale` on `Slider.Root`, or pass a function as `children`.

### Pair With an Input for Exact Values

Some people cannot drag. Where precision matters, add a [NumberField](/docs/components/number-field) beside the slider.

**Do:** Share one value between the slider and the input.

```tsx
/**
 * Do example for "Pair With an Input for Exact Values" on the Slider page.
 * Share one value between the slider and the input.
 * @module
 */
import { NumberField, Slider, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.root()}>
      <span {...styles.label()}>Target load (TPS)</span>
      <div {...styles.row()}>
        <Slider.Root
          aria-label="Target load"
          defaultValue={4000}
          max={10000}
          step={500}
          {...styles.slider()}
        >
          <Slider.Control>
            <Slider.Track>
              <Slider.Indicator />
              <Slider.Thumb />
            </Slider.Track>
          </Slider.Control>
        </Slider.Root>
        <NumberField.Root defaultValue={4000} max={10000} min={0} step={500} {...styles.number()}>
          <NumberField.Group>
            <NumberField.Input aria-label="Target load" />
          </NumberField.Group>
        </NumberField.Root>
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ typography: 'body.b2' })

  // The root keeps its full width, so a maximum narrows it.
  export const number = style({ maxWidth: '6rem !custom' })

  export const root = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '8',
    maxWidth: '20rem !custom',
    width: '100% !custom',
  })

  export const row = style({ alignItems: 'center', display: 'flex', gap: '16' })

  export const slider = style({ flexGrow: '1 !custom' })
}
```

**Don't:** Let the slider and the input hold different values.

```tsx
/**
 * Don't example for "Pair With an Input for Exact Values" on the Slider page.
 * Don't let the slider and the input hold different values.
 * @module
 */
import { NumberField, Slider, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.root()}>
      <span {...styles.label()}>Target load (TPS)</span>
      <div {...styles.row()}>
        <Slider.Root
          aria-label="Target load"
          defaultValue={4000}
          max={10000}
          step={500}
          {...styles.slider()}
        >
          <Slider.Control>
            <Slider.Track>
              <Slider.Indicator />
              <Slider.Thumb />
            </Slider.Track>
          </Slider.Control>
        </Slider.Root>
        <NumberField.Root defaultValue={2500} max={10000} min={0} step={500} {...styles.number()}>
          <NumberField.Group>
            <NumberField.Input aria-label="Target load" />
          </NumberField.Group>
        </NumberField.Root>
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ typography: 'body.b2' })

  // The root keeps its full width, so a maximum narrows it.
  export const number = style({ maxWidth: '6rem !custom' })

  export const root = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '8',
    maxWidth: '20rem !custom',
    width: '100% !custom',
  })

  export const row = style({ alignItems: 'center', display: 'flex', gap: '16' })

  export const slider = style({ flexGrow: '1 !custom' })
}
```

### Choose a Range and Steps That Fit the Data

* **`largeStep`:** Applies to Page Up and Page Down. Size it to cross the range in a few presses.
* **Bounds:** If the label does not make them obvious, show them below the track.
* **`minStepsBetweenValues`:** If an empty range is not valid, set it to keep the thumbs apart.

**Do:** Set `min`, `max`, and `step` to values people think in, such as 500 TPS steps.

```tsx
/**
 * Do example for "Choose a Range and Steps That Fit the Data" on the Slider page.
 * Set `min`, `max`, and `step` to values people think in, such as 500 TPS steps.
 * @module
 */
import { Slider, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Slider.Root
      aria-label="Target load"
      defaultValue={4000}
      max={10000}
      step={500}
      {...styles.root()}
    >
      <div {...styles.header()}>
        <span>Target load</span>
        <span>
          <Slider.Value /> TPS
        </span>
      </div>
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Control>
      <div {...styles.bounds()}>
        <span>0</span>
        <span>10,000</span>
      </div>
    </Slider.Root>
  )
}

namespace styles {
  export const bounds = style({
    color: 'content.secondary',
    display: 'flex',
    justifyContent: 'space-between',
    marginTop: '8',
    typography: 'body.b3',
  })

  export const header = style({
    display: 'flex',
    justifyContent: 'space-between',
    marginBottom: '8',
    typography: 'body.b2',
  })

  export const root = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

**Don't:** Use a step or bounds that produce values such as 4,137.

```tsx
/**
 * Don't example for "Choose a Range and Steps That Fit the Data" on the Slider page.
 * Don't use a step or bounds that produce values such as 4,137.
 * @module
 */
import { Slider, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Slider.Root
      aria-label="Target load"
      defaultValue={4137}
      max={10240}
      step={1}
      {...styles.root()}
    >
      <div {...styles.header()}>
        <span>Target load</span>
        <span>
          <Slider.Value /> TPS
        </span>
      </div>
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Control>
      <div {...styles.bounds()}>
        <span>0</span>
        <span>10,240</span>
      </div>
    </Slider.Root>
  )
}

namespace styles {
  export const bounds = style({
    color: 'content.secondary',
    display: 'flex',
    justifyContent: 'space-between',
    marginTop: '8',
    typography: 'body.b3',
  })

  export const header = style({
    display: 'flex',
    justifyContent: 'space-between',
    marginBottom: '8',
    typography: 'body.b2',
  })

  export const root = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

### Commit Expensive Work on Release

* **Every Movement (onValueChange):** Fires on every movement. Use it to update the visible value.
* **Release (onValueCommitted):** Fires once when the drag, track press, or key press ends. Use it to refetch data or save.

## Content

* **Label:** Name the quantity, such as Target load. Show the unit with the value, such as 4,000 TPS.

## Accessibility

Slider accepts keyboard, pointer, and touch input. It follows the [WAI-ARIA Authoring Practices slider pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/), and the [multi-thumb slider pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/) for a range.

### Semantics

* **Slider.Root (group):** Holds the thumbs as one named group.
* **Slider.Thumb (input type=range):** Wraps a native range input, which holds the name and keyboard focus.
* **Range Values (aria-valuetext):** Each range thumb reads as "20 start range" or "70 end range". `getAriaValueText` replaces it.
* **Slider.Value (output):** Linked to its thumb, and silent during a drag.
* **Disabled (disabled):** Locks every thumb and dims the slider. Explain why nearby.
* **Size and Motion (24px):** The thumb grows slightly during a drag, except under reduced motion.

### Keyboard

* **Move to a Thumb (Tab):** Moves focus to each thumb in order.
* **Increase by Step (Right Arrow or Up Arrow):** Increases the value by `step`.
* **Decrease by Step (Left Arrow or Down Arrow):** Decreases the value by `step`.
* **Increase by Large Step (Page Up or Shift+Right Arrow):** Increases the value by `largeStep`.
* **Decrease by Large Step (Page Down or Shift+Left Arrow):** Decreases the value by `largeStep`.
* **Set to Minimum (Home):** Sets the value to `min`.
* **Set to Maximum (End):** Sets the value to `max`.

In a range, a thumb stops at the other thumb's value.

### Dragging

Every drag has a single-press alternative ([SC 2.5.7](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html)). A press on `Slider.Control` moves the nearest thumb, and the keys above set any value.

### Your Responsibilities

* **Name Every Thumb (aria-label):** Label each thumb with `getAriaLabel` or a field label. A root `aria-label` names only the group.
* **Name Range Thumbs by Role:** Label the thumbs by role, such as "Minimum" and "Maximum".
* **Announce Units (getAriaValueText):** Announce the unit with each value, such as "20 percent".

## Related

[NumberField](/docs/components/number-field)

Use for exact numbers.

[ChoiceGroup](/docs/components/choice-group)

Use for a few preset values.

[Progress](/docs/components/progress)

Use for showing progress you can't change.

[Dashboards](/docs/patterns/dashboards)

Covers chart controls and filters.
