# Slider

A single-thumb slider for selecting a numeric value within a range. It is built on top of [the `Range` component](./range.mdx), and exposes the same behavior through a single-value API.

```tsx demo
import { Slider } from "@tenstorrent/vesper/slider";

export default function SliderDemo() {
  return <Slider thumbAriaLabel="Volume" defaultValue={50} />;
}
```

## Options

| Prop             | Type                      | Description                                                                                   | Default |
| ---------------- | ------------------------- | --------------------------------------------------------------------------------------------- | ------- |
| `thumbAriaLabel` | `string`                  | The accessible `aria-label` for the thumb. Required.                                          | —       |
| `value`          | `number`                  | The value of the thumb (controlled mode).                                                     | —       |
| `defaultValue`   | `number`                  | The initial thumb value (uncontrolled mode).                                                  | `min`   |
| `onValueChange`  | `(value: number) => void` | Callback fired as the thumb value changes during interaction.                                 | —       |
| `onValueCommit`  | `(value: number) => void` | Callback fired when the thumb interaction is completed, eg. on pointer up.                    | —       |
| `min`            | `number`                  | The minimum allowed value.                                                                    | `0`     |
| `max`            | `number`                  | The maximum allowed value.                                                                    | `100`   |
| `step`           | `number`                  | The stepping interval between selectable values.                                              | `1`     |
| `showTicks`      | `boolean`                 | When `true`, renders tick marks along the track at each step interval.                        | `false` |
| `showValueLabel` | `boolean`                 | When `true`, displays a value label above the thumb.                                          | `false` |
| `valueLabel`     | `string`                  | A custom display label for the thumb. When unset, it falls back to the thumb's current value. | —       |
| `disabled`       | `boolean`                 | When `true`, prevents interaction.                                                            | `false` |
| `name`           | `string`                  | The form field name submitted with form data.                                                 | —       |
| `form`           | `string`                  | Associates the slider with a `<form>` element by its `id`.                                    | —       |

All other props are forwarded to the wrapping `<div>` element.

If you need to select a span of values rather than a single one, reach for [the `Range` component](./range.mdx) instead: it renders the same track, but with a thumb per value.

## Examples

### Uncontrolled vs controlled

Render a `Slider` in an **uncontrolled** fashion to let it keep track of its own value. Pass `defaultValue` if the thumb should start somewhere other than `min`:

```tsx demo
import { Slider } from "@tenstorrent/vesper/slider";

export default function UncontrolledSlider() {
  return <Slider defaultValue={30} thumbAriaLabel="Volume" />;
}
```

If you need to control the value, use the `value` and `onValueChange` props. `onValueChange` fires continuously as the thumb is dragged:

```tsx demo
import { useState } from "react";

import { Slider } from "@tenstorrent/vesper/slider";

export default function ControlledSlider() {
  const [volume, setVolume] = useState(75);

  return (
    <Slider value={volume} onValueChange={setVolume} thumbAriaLabel="Volume" />
  );
}
```

Use `onValueCommit` when you only care about the final value of an interaction, eg. to avoid firing a request on every pointer move:

```tsx
import { Slider } from "@tenstorrent/vesper/slider";

export default function VolumeSlider() {
  return (
    <Slider
      defaultValue={50}
      onValueCommit={(volume) => savePreference({ volume })}
      thumbAriaLabel="Volume"
    />
  );
}
```

### Bounds and stepping

`min`, `max`, and `step` describe the values the thumb can take, defaulting to `0`, `100`, and `1`. A `step` of `100` on a range of `0-1000` restricts the thumb to multiples of 100:

```tsx demo
import { Slider } from "@tenstorrent/vesper/slider";

export default function LargeStepSlider() {
  return (
    <Slider
      min={0}
      max={1000}
      step={100}
      defaultValue={500}
      showValueLabel
      thumbAriaLabel="Budget"
    />
  );
}
```

The `step` also determines how far the thumb moves per arrow key press when it is focused.

> [!NOTE]
>
> When neither `value` nor `defaultValue` is provided, the thumb starts at `min` rather than at zero, so a slider with a `min` of `10` starts at `10`.

### Showing ticks

Pass `showTicks` to mark each step along the track. Ticks are rendered between `min` and `max`, so a range of `0-10` with a `step` of `1` renders nine of them:

```tsx demo
import { Slider } from "@tenstorrent/vesper/slider";

export default function SliderWithTicks() {
  return (
    <Slider
      min={0}
      max={10}
      step={1}
      showTicks
      defaultValue={3}
      thumbAriaLabel="Rating"
    />
  );
}
```

> [!NOTE]
>
> Ticks are drawn per step, so a fine `step` on a wide range produces a dense, noisy track. Ticks work best when the range has a handful of stops, eg. a range of `0-100` with a `step` of `10`.

### Value label

Pass `showValueLabel` to render the thumb's current value above it as you drag:

```tsx demo
import { Slider } from "@tenstorrent/vesper/slider";

export default function SliderWithVisibleValueLabel() {
  return <Slider showValueLabel defaultValue={40} thumbAriaLabel="Volume" />;
}
```

Use `valueLabel` to display something other than the raw value, such as a formatted or unit-suffixed one. It is only rendered when `showValueLabel` is also passed:

```tsx demo
import { useState } from "react";

import { Slider } from "@tenstorrent/vesper/slider";

export default function SliderWithCustomValueLabel() {
  const [volume, setVolume] = useState(40);

  return (
    <Slider
      showValueLabel
      value={volume}
      onValueChange={setVolume}
      valueLabel={`${volume}%`}
      thumbAriaLabel="Volume"
    />
  );
}
```

> [!IMPORTANT]
>
> Value label is presentational, and is not announced by assistive technology.
>
> Screen readers announce the underlying numeric value of a thumb instead. If a label carries meaning that the number alone doesn't, such as a currency or a unit, include it in the `thumbAriaLabel` too.

### Keyboard interaction

The thumb is a native `<input type="range">`, so a `Slider` is fully keyboard operable once it is focused:

| Key                       | Behaviour                                      |
| ------------------------- | ---------------------------------------------- |
| `ArrowRight` / `ArrowUp`  | Increases the value by `step`.                 |
| `ArrowLeft` / `ArrowDown` | Decreases the value by `step`.                 |
| `Shift` + any arrow key   | Moves the thumb by 10 units instead of `step`. |
| `PageUp` / `PageDown`     | Increases / decreases the value by 10 units.   |
| `Home`                    | Moves the thumb to `min`.                      |
| `End`                     | Moves the thumb to `max`.                      |

### Disabling the slider

Pass `disabled` to prevent all interaction. A disabled `Slider` still displays its current value, but its thumb is skipped in the tab order and excluded from form data:

```tsx demo
import { Slider } from "@tenstorrent/vesper/slider";

export default function DisabledSlider() {
  return <Slider disabled defaultValue={50} thumbAriaLabel="Volume" />;
}
```

### Usage in forms

The thumb renders a native `<input type="range">`, so passing a `name` includes its value in form submissions. Use the `form` prop to associate the field with a `<form>` rendered elsewhere on the page:

```tsx demo
import { useState } from "react";

import { Button } from "@tenstorrent/vesper/button";
import { Slider } from "@tenstorrent/vesper/slider";
import { Typography } from "@tenstorrent/vesper/typography";

export default function FormSliderDemo() {
  const [submitted, setSubmitted] = useState<string | null>(null);

  return (
    <form
      style={{
        display: "flex",
        flexDirection: "column",
        gap: "var(--vesper-spacing-4)",
      }}
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        setSubmitted(String(data.get("volume") ?? ""));
      }}
    >
      <Slider name="volume" defaultValue={50} thumbAriaLabel="Volume" />
      <Button size="sm" type="submit">
        Submit
      </Button>
      {submitted !== null && (
        <Typography variant="copy-sm">Submitted value: {submitted}</Typography>
      )}
    </form>
  );
}
```

A range input always has a value, so a `Slider` submits its current value even if the user never touches it. The form above submits `volume=50` on an untouched slider.