# Slider Guides
## Patterns
### Volume Or Brightness Control
When to use:
- users adjust one bounded setting quickly
Composition notes:
- show the current value nearby when precision matters
- keep the slider wide enough for comfortable dragging
Trade-offs:
- fast and tactile
- less exact than typed entry
```tsx
import { useState } from 'react';
import {
Label,
Slider,
SliderRange,
SliderThumb,
SliderThumbIndicator,
SliderThumbInput,
SliderTrack,
Text,
} from '@vega-ui/react';
export default function ControlledBrightness() {
const [brightness, setBrightness] = useState(60);
return (
{brightness}%
);
}
```
### Price Range Filter
When to use:
- users pick a lower and an upper bound
Composition notes:
- label both thumbs
- set `minStepsBetweenThumbs` when the bounds must not meet
Trade-offs:
- one control for two related values
- thumbs close together are harder to grab; a click on the track moves the nearest one
```tsx
import { useState } from 'react';
import {
Fieldset,
FieldsetLegend,
Slider,
SliderRange,
SliderThumb,
SliderThumbIndicator,
SliderThumbInput,
SliderTrack,
Text,
} from '@vega-ui/react';
const products = [
{ name: 'Trail runner', price: 89 },
{ name: 'Rain shell', price: 149 },
{ name: 'Down jacket', price: 279 },
{ name: 'Wool beanie', price: 25 },
{ name: 'Hiking boots', price: 189 },
{ name: 'Day pack', price: 65 },
{ name: 'Fleece vest', price: 79 },
{ name: 'Expedition parka', price: 540 },
];
const currency = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });
export default function ControlledRange() {
const [price, setPrice] = useState([50, 200]);
const matching = products.filter((product) => product.price >= price[0] && product.price <= price[1]);
return (
);
}
```
### Vertical Control
When to use:
- the layout is narrow and a vertical control reads better
Composition notes:
- set `orientation='vertical'`
- provide a real height
Trade-offs:
- efficient in certain dense layouts
- easier to render incorrectly than the horizontal default
```tsx
import { useState } from 'react';
import {
Slider,
SliderRange,
SliderThumb,
SliderThumbIndicator,
SliderThumbInput,
SliderTrack,
Text,
} from '@vega-ui/react';
export default function VerticalSlider() {
const [level, setLevel] = useState(70);
return (
{level}%
A vertical slider needs an explicit height. Arrow Up and Arrow Right raise the value, Page Up and Page Down jump by a tenth.
);
}
```
### Value Label On Thumb
When to use:
- the exact value matters while dragging, and there is no room for a separate readout
Composition notes:
- control the value and render it inside `SliderThumbIndicator`, so the label moves with the thumb
- hide the bubble from assistive technology; the input already announces the value
Trade-offs:
- the value stays next to the pointer
- the bubble needs free space above the track
```tsx
import {
Slider,
SliderRange,
SliderThumb,
SliderThumbIndicator,
SliderThumbInput,
SliderTrack,
Text,
} from '@vega-ui/react';
import { useState } from 'react';
export default function ValueLabelOnThumb() {
const [volume, setVolume] = useState(40);
return (
{volume}
);
}
```
### Discrete Steps With Labels
When to use:
- the value is one of a few named options, such as plans or tiers
Composition notes:
- map indexes to labels: `min={0}`, `max` is the last index, `step={1}`
- pass the label as `aria-valuetext`, so screen readers announce the option, not the index
Trade-offs:
- every option is visible at a glance
- works only for a short list; long labels collide under the track
```tsx
import {
Slider,
SliderRange,
SliderThumb,
SliderThumbIndicator,
SliderThumbInput,
SliderTrack,
Text,
} from '@vega-ui/react';
import { useState } from 'react';
const plans = ['1 GB', '5 GB', '20 GB', '100 GB', '1 TB'];
const last = plans.length - 1;
export default function DiscreteStepsWithLabels() {
const [plan, setPlan] = useState(2);
return (
{plans.map((label, index) => (
{label}
))}
);
}
```
## Comparison
### Quick Decision Rule
Use `Slider` when approximate value adjustment is more important than exact typing. Use `NumberField` when users need precise numeric entry.
### `Slider` vs `NumberField`
- Use `Slider` for quick relative adjustment.
- Use `NumberField` for exact numeric control.
### One thumb vs several
- One `SliderThumb` selects a single value.
- Two `SliderThumb`s select a range; `minStepsBetweenThumbs` keeps the ends apart.
### `Slider` vs ``
- Each thumb is the native input, so form and keyboard behavior is the same.
- `Slider` adds the design-system look, several thumbs over one track and the range fill.
### Choose This Component When
- one or a few bounded values are adjusted frequently
- dragging is a better fit than typing
### Do Not Choose This Component When
- exact entry matters most
## Troubleshooting
### The Value Is Missing From Form Submission
#### Symptom
The control works visually, but the form payload does not contain the slider value.
#### Likely Cause
Neither the root nor the thumb has a `name`.
#### How To Verify
- submit the form
- inspect `FormData`
#### Fix
Set `name` on `Slider` or on each `SliderThumbInput`. Several thumbs with one name read with `FormData.getAll`.
### A Controlled Slider Does Not Move
#### Symptom
The thumbs spring back after every drag or key press.
#### Likely Cause
`value` is set but `onChangeValue` does not store the new values.
#### How To Verify
- log the value `onChangeValue` receives
- check that the state passed to `value` changes
#### Fix
Store the value from `onChangeValue` in the state passed to `value`, or use `defaultValue` when the slider does not need to be controlled.
### A Thumb Shows The Wrong Value
#### Symptom
A thumb sits at another thumb's value, or a thumb is missing.
#### Likely Cause
The thumbs have no `index`, two share one, or the number of thumbs differs from the number of values.
#### How To Verify
- compare the `index` of every `SliderThumb` with the length of `value` or `defaultValue`
#### Fix
Render one `SliderThumb` per value with `index={0}`, `index={1}`… in order.
### The Vertical Slider Is Hard To Use Or Invisible
#### Symptom
The vertical slider renders poorly or has almost no usable track.
#### Likely Cause
The root was switched to vertical orientation without an explicit height.
#### How To Verify
- inspect the computed height of the slider container
#### Fix
Provide a real height whenever `orientation='vertical'` is used.
### Users Cannot Reach The Exact Value Reliably
#### Symptom
Dragging feels imprecise for the intended task.
#### Likely Cause
The control is being used for an exact-entry scenario.
#### How To Verify
- test with the real required precision, not just rough adjustments
#### Fix
Switch to `NumberField` or pair the slider with a more precise companion input.