---
description: Компонент, который позволяет пользователю выбрать значение из заданного диапазона,
  перемещая ползунок по горизонтальной шкале.
tags: selection
---

<Overview group="forms">

# Slider [tag:component]

Компонент, который позволяет пользователю выбрать значение из заданного диапазона, перемещая ползунок по горизонтальной шкале.
Поддерживает как выбор одного значения, так и диапазона значений.

</Overview>

import { BlockWrapper } from '@/components/wrappers';

{/* @example-description: Базовый одноползунковый `Slider` с начальным значением. */}
<Playground Wrapper={BlockWrapper} style={{ width: 270 }}>
  ```jsx
  <Slider defaultValue={30} />
  ```
</Playground>

## Режим работы

Компонент поддерживает работу как в неконтролируемом режиме, так и контролируемом. Это стандартное поведение
React-компонентов, прочитать про это можно в [документации React](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable).

Для использования неконтролируемого режима достаточно просто _не_ передавать `value` или передавать `defaultValue`, если
требуется задать значение по умолчанию.
Для контролируемого режима используйте связку свойств `value`/`onChange` для задания значения и его изменения.

```jsx
// Неконтролируемое состояние
<Slider step={0.2} min={0} max={1} defaultValue={0.4} />;

// Контролируемое состояние
const [valueStep, setValueStep] = useState(0.4);

<Slider step={0.2} min={0} max={1} value={valueStep} onChange={setValueStep} />;
```

## Диапазон значений

Для возможности задать диапазон значений, передавайте свойство `multiple={true}`.

В таком случае свойства `defaultValue` или `value` (для неконтролируемого режима и контролируемого соответственно)
принимают массив из двух числовых значений - `[m,n]` (где `m` - значение начального ползунка, `n` - конечного).

{/* @example-description: Диапазонный `Slider` с двумя ползунками через `multiple={true}`. */}
<Playground Wrapper={BlockWrapper} style={{ width: 270 }}>
  ```jsx
  <Slider defaultValue={[25, 75]} multiple />
  ```
</Playground>

## Размеры ползунков

Задаётся свойством `size`.

- `"s"` — маленький;
- `"m"` — средний;
- `"l"` — большой (по умолчанию).

Значения, соответствующие каждому размеру, зависят от параметра адаптивности `density`.
В режиме `density="regular"` (мобильные устройства) значения каждого из размеров будут увеличены по сравнению с `density="compact"`.

## Всплывающая подсказка

Задаётся свойством `withTooltip`.

При значении свойства `withTooltip={true}` наведение на ползунок или фокус на нём вызывает появление
всплывающей подсказки с текущим значением. Это особенно полезно, когда точное значение важно для пользователя.

> Изменить контент, который будет отображен в подсказке - нельзя.

{/* @example-description: `Slider` с всплывающей подсказкой текущего значения через `withTooltip`. */}
<Playground Wrapper={BlockWrapper} style={{ width: 270 }}>
  ```jsx
  <Slider defaultValue={30} withTooltip />
  ```
</Playground>

## Состояния

### `disabled`

Свойство `disabled` блокирует взаимодействие с компонентом и добавляет визуальную индикацию недоступности.

{/* @example-description: `Slider` в неактивном состоянии `disabled`. */}
<Playground Wrapper={BlockWrapper} style={{ maxWidth: 270 }}>
  ```jsx
  <Slider defaultValue={30} disabled />
  ```
</Playground>

## Тестирование (e2e) [#e2e]

Для возможности тестирования доступны свойства с постфиксом `*TestId`, которые вы можете использовать,
чтобы находить необходимые части компонента:

- `startThumbTestId` — `id` для первого (начального) ползунка;
- `endThumbTestId` — `id` для второго (конечного) ползунка (только при `multiple={true}`).

```jsx
<Slider multiple startThumbTestId="startSlider" endThumbTestId="endSlider" />
```

## Доступность (a11y) [#a11y]

Компонент реализован с учётом требований доступности:

- использует нативный элемент `input[type="range"]` для базовой доступности;
- поддерживает управление с клавиатуры (стрелки влево/вправо для изменения значения);
- поддерживает все стандартные `aria`-атрибуты.

Для корректной работы скринридеров необходимо вручную передавать некоторые параметры:

- для обозначения того, за что отвечает ползунок, следует передать либо `aria-label`, либо `aria-labelledby`;
- по умолчанию скринридер будет читать значение, которое передаётся в `value`/`defaultValue`. Чтобы
  повлиять на это, используйте `aria-valuetext` или `getAriaValueText`. Первое свойство полезно для
  контролируемого компонента, а второе для неконтролируемого, потому что в параметрах передаёт текущее значение ползунка.

## Свойства и методы [#api]

| Свойство | Тип | По умолчанию | Описание |
| --- | --- | --- | --- |
| `defaultValue` | `number \| [number, number]` | `multipleProp ? [min, max] : min` | Значение слайдера по умолчанию. Значения слайдера по умолчанию в виде массива [начальное, конечное]. |
| `disabled` | `boolean` | `-` | Блокировка взаимодействия с компонентом. |
| `endThumbTestId` | `string` | `-` | Передает атрибут `data-testid` для второго ползунка когда `multiple=true`. |
| `getAriaLabel` | `((index: number) => string)` | `-` | Тоже самое, что и `aria-label`, но на вход можно получать индекс текущего ползунка и в зависимости от этого выдавать разный текст.  > Перебивает `aria-label`. |
| `getAriaValueText` | `((value: number, index: number) => string)` | `-` | В отличие от `aria-valuetext`, позволяет более гибко форматировать текст в зависимости от значения ползунка.  Полезно при использовании компонента как неконтролируемого.  > Перебивает `aria-valuetext`. |
| `getRootRef` | `Ref<HTMLDivElement>` | `-` |  |
| `max` | `number` | `100` | Максимальное значение слайдера. |
| `min` | `number` | `0` | Минимальное значение слайдера. |
| `multiple` | `boolean` | `-` | Флаг множественного выбора (должен быть false или не указан). Флаг множественного выбора (должен быть true). |
| `onChange` | `((value: number, event: CustomTouchEvent \| ChangeEvent<Element>) => void) \| ((value: [number, number], event: CustomTouchEvent \| ChangeEvent<...>) => void)` | `-` | Обработчик изменения значения слайдера. Обработчик изменения значений слайдера. |
| `size` | `"s" \| "m" \| "l"` | `l` | Размер ползунка. |
| `startThumbTestId` | `string` | `-` | Передает атрибут `data-testid` для первого ползунка. |
| `step` | `number` | `1` | Шаг изменения значения слайдера. |
| `value` | `number \| [number, number]` | `-` | Текущее значение слайдера. Текущие значения слайдера в виде массива [начальное, конечное]. |
| `withTooltip` | `boolean` | `-` | Включает отображение всплывающей подсказки при взаимодействии с ползунком. |