# Slider ## Кратко `Slider` — [составной компонент](https://vega-ui.dev/ru/docs/glossary/#составной-компонент-compound-component) для выбора одного или нескольких чисел из ограниченного диапазона. Каждый `SliderThumbInput` — это нативный ``, наложенный на один `SliderTrack`, поэтому клавиатура, фокус, отправка и сброс формы и вспомогательные технологии работают как с нативным элементом. Два бегунка превращают слайдер в слайдер диапазона. ## Импорт ```tsx import { Slider, SliderRange, SliderThumb, SliderThumbInput, SliderThumbIndicator, SliderTrack, useSliderContext, useSliderThumbContext, type SliderOrientation, type SliderProps, type SliderRangeProps, type SliderSize, type SliderThumbProps, type SliderThumbInputProps, type SliderThumbIndicatorProps, type SliderTrackProps, type SliderVariant, } from '@vega-ui/react'; ``` ## Экспортируемые типы - `SliderProps` - `SliderTrackProps` - `SliderRangeProps` - `SliderThumbProps` - `SliderThumbInputProps` - `SliderThumbIndicatorProps` - `SliderSize` - `SliderVariant` - `SliderOrientation` ## Минимальная композиция ```tsx import { Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, } from '@vega-ui/react'; export default function MinimalComposition() { return ( ); } ``` ## Обязательные части - `Slider`: корень, значения всех бегунков и общие настройки диапазона - `SliderThumb`: один бегунок на каждое значение - `SliderThumbInput`: нативное поле range у бегунка ## Необязательные части - `SliderTrack`: видимая дорожка - `SliderRange`: заполненная часть дорожки внутри `SliderTrack` - `SliderThumbIndicator`: визуальный бегунок; без него бегунок невидим ## Порядок композиции 1. `Slider` 2. `SliderTrack` > `SliderRange` 3. `SliderThumb` — по одному на значение, `index` по порядку от `min` к `max`, внутри `SliderThumbInput` и `SliderThumbIndicator` ## Варианты - Размер: `sm`, `md`, `lg` - Вариант: `primary`, `secondary` - Ориентация: `horizontal` или `vertical` - Бегунки: одно значение или диапазон из нескольких - Модель значения: контролируемая или неконтролируемая на корне, число для одного бегунка или массив для нескольких - Шаг: числовой шаг или `'any'` ## Пограничные случаи - Попасть в точное значение слайдером труднее, чем набрать его в поле. - Вертикальным слайдерам нужна явная высота. - Бегунки не могут обогнать друг друга; `minStepsBetweenThumbs` сохраняет промежуток между ними. - Без `value` или `defaultValue` у слайдера один бегунок посередине, как у ``. ## Частые ошибки - Слайдер используют там, где главное — точный ввод числа. - Забывают показать видимое значение в сценариях, где важна точность. - Оставляют бегунки без `aria-label` или `aria-labelledby`. - Рендерят число `SliderThumb`, отличное от числа значений, или дают двум бегункам одинаковый `index`. ## Примеры ### Базовый #### Базовый: слайдер с подписью и значением по умолчанию Неконтролируемый слайдер: `defaultValue` задаёт начальное значение, а `name` на корне доходит до поля бегунка. `SliderThumbInput` — нативный ``, поэтому видимый `Label` ссылается на его `id`. ```tsx import { Label, Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, } from '@vega-ui/react'; export default function SliderWithDefaultValue() { return (
); } ``` #### Базовый: два бегунка для диапазона Массив в `defaultValue` задаёт по значению на каждый `SliderThumb` по его `index`. Каждое поле бегунка получает свой `name` и `aria-label`, а `minStepsBetweenThumbs` не даёт смене стать короче часа. ```tsx import { Fieldset, FieldsetLegend, Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, } from '@vega-ui/react'; export default function RangeSlider() { return (
Working hours
); } ``` ### Контролируемый/с состоянием #### Контролируемый/с состоянием: значение, управляющее превью `value` с `onChangeValue` держит число в родителе: подпись и образец цвета следуют за ним во время перетаскивания. `aria-valuetext` объявляет значение вместе с единицей измерения. ```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}%
); } ``` #### Контролируемый/с состоянием: фильтр цены по списку товаров Контролируемый диапазон с двумя бегунками фильтрует список прямо во время движения. Цены форматируются одним `Intl.NumberFormat`, который используется и для подписи, и для `aria-valuetext` каждого бегунка. ```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 (
Price {currency.format(price[0])} – {currency.format(price[1])}
{matching.length} of {products.length} products{matching.length > 0 ? `: ${matching.map((product) => product.name).join(', ')}` : ''}
); } ``` #### Контролируемый/с состоянием: добавление и удаление бегунков Число бегунков следует за длиной массива `value`: рендерите по одному `SliderThumb` на элемент. Бегунки остаются упорядоченными и на расстоянии `minStepsBetweenThumbs`, а каждый получает подпись по своей позиции. ```tsx import { useState } from 'react'; import { Button, Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, Text, } from '@vega-ui/react'; const tierNames = ['Free', 'Starter', 'Growth', 'Scale', 'Enterprise']; export default function AnyNumberOfThumbs() { const [limits, setLimits] = useState([1000, 10000, 50000]); const addLimit = () => { const last = limits[limits.length - 1]; if (last >= 95000) return; setLimits([...limits, Math.min(last + 20000, 100000)]); }; const removeLimit = () => { setLimits(limits.slice(0, -1)); }; return (
{limits.map((limit, index) => ( ))} {limits.map((limit, index) => `${tierNames[index]}: up to ${limit.toLocaleString('en-US')}`).join(' · ')}
); } ``` ### Форма/интеграция #### Форма/интеграция: чтение значений через FormData Диапазон с `name` на корне отправляет по записи на каждый бегунок, поэтому `FormData.getAll('age')` возвращает обе границы; одиночный бегунок читается через `FormData.get`. Сброс формы возвращает `defaultValue`. ```tsx import { FormEvent, useState } from 'react'; import { Button, Fieldset, FieldsetLegend, Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, Text, } from '@vega-ui/react'; export default function NativeFormValue() { const [result, setResult] = useState(''); const handleSubmit = (event: FormEvent) => { event.preventDefault(); const data = new FormData(event.currentTarget); setResult(`age=${data.getAll('age').join('–')}, radius=${data.get('radius')} km`); }; return (
setResult('')} style={{ display: 'grid', gap: 'var(--spacing-12)', width: '100%', maxWidth: 400 }}>
Audience age
Delivery radius
{result}
); } ``` ### Раскладка/оверлей #### Раскладка/оверлей: вертикальный слайдер `orientation='vertical'` растёт снизу вверх, и ему нужна явная высота. Значение показано под дорожкой, а клавиатура работает по обеим осям стрелок. ```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.
); } ``` #### Раскладка/оверлей: слайдер громкости в поповере Триггер-иконка открывает `Popover` с вертикальным слайдером. `aria-label` триггера включает текущее значение, поэтому оно объявляется без открытия поповера, а иконка следует за значением. ```tsx import { useState } from 'react'; import { Icon, IconButton, Popover, PopoverContent, PopoverTrigger, Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, } from '@vega-ui/react'; import { Volume1Icon, Volume2Icon, VolumeXIcon } from '@vega-ui/icons'; export default function SliderInAPopover() { const [volume, setVolume] = useState(40); let VolumeIcon = Volume2Icon; if (volume === 0) { VolumeIcon = VolumeXIcon; } else if (volume < 50) { VolumeIcon = Volume1Icon; } return (
); } ``` ### Ошибка #### Ошибка: значение выше лимита политики Слайдер допускает весь диапазон, но значения выше лимита политики невалидны: поле бегунка получает `aria-invalid` и `aria-describedby` со ссылкой на ошибку, которая исчезает, когда значение возвращается в пределы лимита. ```tsx import { useState } from 'react'; import { HelperText, Label, Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, Text, } from '@vega-ui/react'; const policyLimit = 80; export default function ValueOutsidePolicyHint() { const [cpu, setCpu] = useState(90); const invalid = cpu > policyLimit; return (
{cpu}%
{invalid && ( Shared clusters allow up to {policyLimit}%. Lower the limit to save. )}
); } ``` ### Отключённый #### Отключённый: заблокированное значение и отключение через fieldset `disabled` на корне блокирует все бегунки; причина связана через `aria-describedby`. Слайдер внутри `Fieldset disabled` отключается нативно и тоже выглядит отключённым — здесь, пока включена автоматическая яркость. ```tsx import { useState } from 'react'; import { Fieldset, FieldsetLegend, HelperText, Label, Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, Switch, SwitchIndicator, SwitchInput, } from '@vega-ui/react'; export default function LockedSlider() { const [automatic, setAutomatic] = useState(true); return (
Set by your compliance policy: 90 days.
setAutomatic(event.currentTarget.checked)} />
Manual brightness
); } ``` ### Пограничный случай #### Пограничный случай: произвольная точность со step any `step='any'` убирает сетку шагов, и значение может быть любой дробью между `min` и `max`. Стрелки тогда сдвигают на сотую часть диапазона; подпись округляет значение для показа. ```tsx import { useState } from 'react'; import { Label, Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, Text, } from '@vega-ui/react'; export default function FreePrecisionStep() { const [opacity, setOpacity] = useState(0.35); return (
{opacity.toFixed(3)}
); } ``` #### Пограничный случай: текст значения с единицами и отрицательным минимумом Диапазон от −10 до 30 с `aria-valuetext`, чтобы скринридер говорил «20 °C», а не голое число. ```tsx import { Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, } from '@vega-ui/react'; import { useState } from 'react'; export default function ValueTextForScreenReaders() { const [temperature, setTemperature] = useState(20); return ( ); } ``` #### Пограничный случай: прилипание к меткам datalist ``, подключённый через `list`, заставляет нативное поле прилипать к своим значениям при перетаскивании. Браузер не рисует метки, поэтому, если они должны быть видны, нарисуйте их сами. ```tsx import { Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, } from '@vega-ui/react'; export default function MarkersFromADatalist() { return ( <> ); } ``` #### Пограничный случай: группа вертикальных слайдеров с отрицательным диапазоном Пять вертикальных слайдеров от −12 до +12 дБ образуют эквалайзер внутри подписанной `role='group'`. Каждый бегунок назван по своей полосе и объявляет усиление в дБ. ```tsx import { Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, Text, } from '@vega-ui/react'; import { useState } from 'react'; const bands = ['60 Hz', '230 Hz', '910 Hz', '3.6 kHz', '14 kHz']; export default function VerticalGroupNegativeRange() { const [gains, setGains] = useState([4, 2, 0, -2, 3]); const changeGain = (band: number, gain: number) => { setGains((current) => current.map((value, index) => (index === band ? gain : value))); }; return (
{bands.map((band, index) => (
changeGain(index, gain)} style={{ height: 200 }} > {band}
))}
); } ``` ## Анатомия ### Обзор `Slider` хранит значения всех бегунков и общие настройки (`min`, `max`, `step`, `orientation`, `disabled`, `name`). Каждый `SliderThumb` объединяет `SliderThumbInput` — нативный ``, наложенный на свой участок дорожки между соседями, — и `SliderThumbIndicator`, который рисуется в точке его значения. ### Обязательные части #### `Slider` Обязательна. Передаёт бегункам настройки диапазона и не даёт соседним бегункам сблизиться. Вертикальному слайдеру нужна высота от родителя. #### `SliderThumb` Обязательна. Один бегунок: `index` выбирает его элемент в `value` корня, а переменные положения задаются для его частей. #### `SliderThumbInput` Обязательна, прямой потомок `SliderThumb`. Контролируемое нативное поле range: фокус, клавиатура, значение в форме и доступность обеспечивает браузер; его `min` и `max` — это соседи. ### Необязательные части #### `SliderThumbIndicator` Визуальный бегунок, прямой потомок `SliderThumb`. Может содержать что угодно: пузырёк со значением, иконку, изображение. Пропускает указатель к нативному полю под ним. #### `SliderTrack` Видимая дорожка. Без неё бегунки всё равно работают над невидимой дорожкой. #### `SliderRange` Заполненная часть дорожки: от `min` до единственного бегунка или между первым и последним бегунками. ### Порядок композиции 1. `Slider` 2. `SliderTrack` > `SliderRange` 3. `SliderThumb` — по одному на значение 1. `SliderThumbInput` 2. `SliderThumbIndicator` ### Корректные варианты композиции ```tsx import { Fieldset, FieldsetLegend, Slider, SliderRange, SliderThumb, SliderThumbIndicator, SliderThumbInput, SliderTrack, } from '@vega-ui/react'; export default function RangeSlider() { return (
Working hours
); } ``` ### Некорректные варианты композиции #### Корень без бегунков Дорожка рендерится, но взаимодействовать и отправлять нечего. #### Бегунки вне корня `SliderThumb` читает настройки из корня и позиционируется над дорожкой корня. #### Поле ввода или индикатор вне `SliderThumb` Они читают свой `index` из `SliderThumb`; стили наведения, нажатия, фокуса и отключённого состояния индикатора следуют за полем ввода того же `SliderThumb`. #### Вертикальный слайдер без высоты Элемент рендерится, но область взаимодействия схлопывается.