# Slider

> Picks a number or a range by dragging along a track, with steps, marks and a value readout.

Category: Forms. Docs page: https://rime.mjsons.net/components/slider

## Installation

```bash
npx shadcn@latest add KezLahd/rime/slider
```

Slider takes one value or a [low, high] range (two thumbs that never cross). The chosen span is drawn in the accent gradient over a recessed track. step snaps every value, marks draw labelled ticks, and showValue prints the formatted value beside the label.

Use it where the exact number matters less than its position in a range (volume, a price filter, a threshold). When the exact number matters, pair it with a TextInput or use the input alone.

## Usage

```tsx
import { Slider } from "@/components/ui";

<Slider label="Volume" value={volume} onValueChange={setVolume} showValue formatValue={(n) => `${n}%`} />
```

## Props: Slider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `step` | `number` | `1` |  |
| `largeStep` | `number` |  | PageUp and PageDown move by this much. Defaults to a tenth of the range, rounded to the step. |
| `marks` | `ReadonlyArray<{ value: number; label?: string }>` |  | Ticks under the track, optionally labelled: [{ value: 0, label: "0" }, { value: 50 }]. |
| `formatValue` | `(value: number) => string` | `(v: number) => String(v)` | Formats the value for aria-valuetext and the value readout: (v) => `${v}%`. |
| `showValue` | `boolean` |  | Shows the formatted value (or range) to the right of the label row. |
| `label` | `string` |  | Visible label above the track. Without it, pass aria-label. |
| `aria-label` | `string` |  |  |
| `disabled` | `boolean` |  |  |
| `name` | `string` |  | Posts the value (a range posts two inputs, name[0] and name[1]). |
| `className` | `string` |  |  |
| `value` (required) | `number \| readonly [number, number]` |  | One thumb. |
| `onValueChange` (required) | `(value: number) => void \| (value: [number, number]) => void` |  |  |

## Examples

### Single value

```tsx
<Slider label="Volume" value={v} onValueChange={setV} showValue formatValue={(n) => `${n}%`} />
```

### Range with marks

```tsx
<Slider
  label="Order value"
  value={range}
  onValueChange={setRange}
  min={0}
  max={1000}
  step={50}
  showValue
  formatValue={(n) => `$${n}`}
  marks={[{ value: 0, label: "$0" }, { value: 500, label: "$500" }, { value: 1000, label: "$1,000" }]}
/>
```

### Step and disabled

```tsx
<Slider label="Step 5" value={35} onValueChange={set} step={5} showValue />
<Slider label="Disabled" value={40} onValueChange={set} disabled />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--slider-fill` | `var(--brand-gradient)` |
| `--slider-thumb-bg` | `var(--surface-solid)` |
| `--slider-thumb-size` | `18px` |
| `--slider-track-bg` | `var(--recess-fill-hover)` |
| `--slider-track-h` | `6px` |

System tokens it reads: `--brand`, `--brand-gradient`, `--dur`, `--ease`, `--focus-ring`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--ink-secondary`, `--line-input`, `--r-full`, `--recess-fill-hover`, `--rgb-contact`, `--surface-solid`, `--text-caption`, `--text-small`.

## Accessibility

- Each thumb is role="slider" with aria-valuemin, aria-valuemax, aria-valuenow and aria-valuetext (from formatValue), named by the label; range thumbs are named "minimum" and "maximum".
- Keyboard: arrows step, PageUp and PageDown take a large step (a tenth of the range by default), Home and End jump to the ends.
- Pressing anywhere on the track moves the nearest thumb there and focuses it.

## Do

- Format values in the unit people think in ("$500", "60%").
- Use marks for meaningful stops only.

## Don't

- Don't use a slider for a value that must be exact; offer a text field too.
- Don't hide the current value when it matters; turn on showValue.

Related: https://rime.mjsons.net/components/meter, https://rime.mjsons.net/components/text-input