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

# Slider \[tag:component]

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

```jsx
<Slider defaultValue={30} />
```

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

Компонент поддерживает работу как в неконтролируемом режиме, так и контролируемом. Это стандартное поведение
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` - конечного).

```jsx
<Slider defaultValue={[25, 75]} multiple />
```

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

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

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

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

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

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

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

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

```jsx
<Slider defaultValue={30} withTooltip />
```

## Состояния

### `disabled`

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

```jsx
<Slider defaultValue={30} disabled />
```

## Тестирование (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, Element>) => void) \| ((value: [number, number], event: CustomTouchEvent \| ChangeEvent<...>) => void)` | `-`                               | Обработчик изменения значения слайдера. Обработчик изменения значений слайдера.                                                                                                                           |
| `ref`              | `Ref<HTMLDivElement>`                                                                                                                                                     | `-`                               |                                                                                                                                                                                                           |
| `size`             | `"s" \| "m" \| "l"`                                                                                                                                                       | `l`                               | Размер ползунка.                                                                                                                                                                                          |
| `startThumbTestId` | `string`                                                                                                                                                                  | `-`                               | Передает атрибут `data-testid` для первого ползунка.                                                                                                                                                      |
| `step`             | `number`                                                                                                                                                                  | `1`                               | Шаг изменения значения слайдера.                                                                                                                                                                          |
| `value`            | `number \| [number, number]`                                                                                                                                              | `-`                               | Текущее значение слайдера. Текущие значения слайдера в виде массива \[начальное, конечное].                                                                                                               |
| `withTooltip`      | `boolean`                                                                                                                                                                 | `-`                               | Включает отображение всплывающей подсказки при взаимодействии с ползунком.                                                                                                                                |
