---
name: slider-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Slider for
single or range numeric adjustment with Zag.js slider behavior, label,
markers, value text, orientation, min/max/step, validation status, and token
styling.
metadata:
component_version: "1.5.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: "https://zagjs.com/components/react/slider"
contributor_sources: "libs/ui/src/molecules/slider.tsx libs/ui/src/tokens/components/molecules/_slider.css libs/ui/stories/molecules/slider.stories.tsx"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit Slider Usage
Use Slider for bounded numeric adjustment. Use NumericInput when exact typed
entry is required.
## Shared field contract
Canonical sizes are `sm`, `md` (default), and `lg`. `showValueText` formats every
thumb count: one value, a two-value range, or an ordered list of several values.
Pass one `aria-label` per thumb (for example `Minimum price` and `Maximum price`);
these explicit names take precedence over the shared visible label.
`helpText` has a stable message ID merged with caller `aria-describedby` on each
focusable thumb. Error status sets `aria-invalid` and `aria-errormessage` on the
thumbs; non-neutral feedback always includes a status icon. Markers reserve a
separate line above help text. `readOnly` keeps thumbs focusable, full contrast
and immutable by pointer and keyboard; `disabled` removes their normal tab stops.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Slider`.
**Use it when**
- Approximate values in a range where visual feedback matters: price range filters, volume, zoom.
**Use something else when**
| Need | Use instead |
| --- | --- |
| Exact values | NumericInput / FormNumericInput |
| Few discrete options | RadioGroup / Select |
**Do**
- Show the current value(s) formatted (`€20 – €80`), and pair price ranges with numeric inputs.
- Use sensible steps; label min and max.
- Apply filter changes on release, not on every pixel.
**Don't**
- Use a slider for values the user must set exactly (quantity, price in admin).
**Copy and states**
- Thumb labels `Minimum price`, `Maximum price`.
**Behaviour (from the UX spec)**
- Every value is reachable by keyboard, not only by precise dragging; values and units are readable as text.
- Dragging is a draft: apply on `onChangeEnd`. In a drafted filter panel, Cancel restores the last applied range.
- An invalid range is `validateStatus="error"`; a valid range with 0 results is a normal empty result, not an error.
**Figma → code**
| Figma | Code |
| --- | --- |
| two-thumb range only | `value` array: one thumb, two (range) or more |
| `state=invalid` | `validateStatus="error"` |
| `state=disabled` | `disabled` |
| no read-only state | `readOnly` |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/Slider → UX guidelines*.
## Setup
```tsx
```
Supported props:
```text
value/defaultValue: number[]
min, max, step, minStepsBetweenThumbs
orientation: horizontal | vertical
origin: start | center | end
thumbAlignment: center | contain
showMarkers, markerCount, showValueText
formatRangeText, formatValue
validateStatus, helpText, onChange, onChangeEnd
size: sm | md | lg
```
A slider without a visible `label` (a price filter under an accordion title)
names its thumbs with `aria-label`, one entry per thumb:
``.
## Core Patterns
### Use array values
Slider values are arrays. A range has two numbers; a single slider can use one
number.
### Use markers for scale cues
Use `showMarkers` and `markerCount`, not custom tick markup.
### Use NumericInput for precision
If the user must type an exact value, use NumericInput or pair both components
deliberately.
## Focus refs and native form lifecycle
`getThumbProps(index)` accepts only `ref`, `onFocus` and `onBlur` for the
zero-based thumb. The ref is a `HTMLDivElement` with `role="slider"`, not its
hidden form input. Focus/blur handlers compose with the machine; do not replace
its keyboard handlers or set thumb values through the DOM. Object refs and
React 19 callback-ref cleanup are supported, including thumb removal.
```tsx
import { useRef, useState } from "react"
import { Button } from "@techsio/ui-kit/atoms/button"
import { Slider } from "@techsio/ui-kit/molecules/slider"
function Budget() {
const [values, setValues] = useState([20, 80])
const minimum = useRef(null)
const maximum = useRef(null)
return <>
({ ref: index === 0 ? minimum : maximum })} />
>
}
```
Use `name` for native form values and `form` for an external owner. Owner changes
follow the actual native input association (including moved forms or changed
IDs). Uncontrolled reset restores the initial defaults under the current bounds
only after all native/React reset listeners can cancel it. `preventDefault()`
in `onReset` preserves the value and emits no reset proposal. Pending work is
cleaned up on unmount. Controlled `value` remains authoritative, including when
the parent rejects a proposal; reset does not silently rewrite parent state.
If the product needs a controlled reset, the app explicitly sets that state.
Native disabled fieldsets (including nested fieldsets and first-legend
exceptions) affect thumbs and submission; read-only remains focusable and
submittable. Runtime bounds/precision normalization and removed-thumb recovery
must not be mistaken for app consent to commit a different controlled value.
The component-owned ThumbFocus/native-form stories cover these contracts.
## Common Mistakes
### HIGH Native range input
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/molecules/slider.tsx
### HIGH Scalar value
Wrong:
```tsx
```
Correct:
```tsx
```
Source: https://zagjs.com/components/react/slider
### HIGH Inline track styling
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/tokens/components/molecules/_slider.css
## Validation Commands
```sh
rg -n "]*type=\"range\"|]*value=\\{[0-9]" apps
rg -n "]*className=.*(bg-|rounded-|h-|w-|text-)" apps
rg -n "showMarkers|markerCount|formatRangeText|onChangeEnd" apps
```
Every multi-thumb slider needs distinct, contextual `aria-label` entries even when `label` is visible. Missing/duplicate names emit a warning. `getAriaValueText({value,index})` overrides spoken values per thumb and defaults to `formatValue(value)`; `formatRangeText` formats only the visible group summary. Inherited disabling follows native fieldset semantics, including disabled outer fieldsets and the first-legend exemption; dynamic changes update machine interactivity, thumb tab order and form submission together.
## Silent native form reset
Native form reset calls no value-change callbacks and dispatches no native
`input` or `change` events. Uncontrolled controls silently restore their default;
controlled controls keep the latest parent value and re-sync visible text, native
value and FormData. Handle the form's `onReset` to intentionally change parent
state. Canceled resets change nothing. React's value tracker is re-synced after
restoration, so the next identical user edit notifies exactly once. Reset does
not move focus.
Read-only thumbs remain pointer-focusable as well as keyboard-focusable,
without changing their values or starting a drag. Disabled thumbs do not gain
this pointer-focus affordance.
Serialize ARIA values and bounds in decimal notation for tiny steps.