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

<Overview group="dates">

# DateRangeInput [tag:component]

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

</Overview>

{/* @example-description: Базовый `DateRangeInput` для выбора периода из двух дат. */}
<Playground style={{ width: 'fit-content' }}>
  ```jsx
  <DateRangeInput />
  ```
</Playground>

## Применение компонента

> Данный компонент предназначен для использования на планшетах и десктопах.
> При использовании на мобильных устройствах работа компонента не гарантируется.

Данный компонент представляет собой поле формы с возможностью вызова календаря.

Если вам нужен отдельный компонент календаря для выбора диапазона дат, то используйте [`CalendarRange`](/components/calendar-range).

Если вам нужно поле ввода одиночной даты и времени (со всплывающим календарём), то используйте [`DateInput`](/components/date-input).

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

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

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

```jsx
// Неконтролируемое состояние
<DateRangeInput defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 10)]} />;

// Контролируемое состояние
const [date, setDate] = React.useState([new Date(2024, 2, 1), new Date(2024, 2, 10)]);

<DateRangeInput value={date} onChange={setDate} />;
```

## Состояния

### `disabled`

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

{/* @example-description: `DateRangeInput` в неактивном состоянии с заданным диапазоном дат. */}
<Playground style={{ width: 'fit-content' }}>
  ```jsx
  <DateRangeInput
    defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 10)]}
    disabled
  />
  ```
</Playground>

## Валидация

Свойство `status` используется для визуализации валидации компонента - некорректности заполненного поля (значение `"error"`)
или успешной валидации (значение `"valid"`).

> Если вы используете `DateRangeInput` вместе с [`FormItem`](/components/form-item), вам достаточно указать свойство `status` только у
> [`FormItem`](/components/form-item).

{/* @example-description: Примеры валидации `DateRangeInput` со статусами `error` и `valid`. */}
<Playground style={{ width: 'fit-content' }}>
  ```jsx
  <Flex direction="column" gap="m">
    <DateRangeInput
      status="error"
      defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 10)]}
    />
    <DateRangeInput
      status="valid"
      defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 10)]}
    />
  </Flex>
  ```
</Playground>

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

Для тестирования компонента можно использовать следующие свойство определяющие `data-testid` атрибуты:

- `calendarTestsProps`
- `startDateTestsProps`
- `endDateTestsProps`
- `showCalendarButtonTestId`
- `clearButtonTestId`

Подробности смотри в [Свойства и методы](#api).

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

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

Новое, доступное поведение можно включить с помощью нового свойства `accessible`.

С `v8` этой свойство включено по умолчанию. Рекомендуется не отключать это поведение, так как этот флаг будет выключен в `v9`

Вот список изменений которые отличают поведение со свойством `accessible` от поведения без:

- иконка календаря видна постоянно (раньше она была видна, только если в `DateRangeInput` нет значения);
- календарь открывается только по клику по иконке календаря, по клику на поле ввода и нажатию клавиши `<Space>`,
  если `DateRangeInput` в фокусе (раньше он открывался сразу при фокусе на `DateRangeInput`);
- при открытии календарь получает фокус. При закрытии календаря фокус возвращается на `DateRangeInput`. Если нужно
  отключить это поведение, используйте свойство `disableFocusTrap`. Если нужно больше контроля над тем, куда возвращать фокус,
  используйте свойство `restoreFocus`.

Из-за особенности реализации `DateRangeInput`, если вкладывать его внутрь `label`, или связывать `label` и `DateRangeInput` через `htmlFor`,
то по клику на `label` фокус будет попадать на `DateRangeInput`, но текст `label` скринридером зачитываться в момент фокуса не будет.
Рекомендуем дублировать текст `label` в `DateRangeInput`, передавая в `DateRangeInput` текст через свойство `aria-label`.

```jsx
<label>
  Период проживания
  <DateRangeInput aria-label="Период проживания" />
</label>
```

```jsx
<label htmlFor="date">Срок действия договора</label>
<DateRangeInput
  id="date"
  aria-label="Срок действия договора"
/>
```

```jsx
<FormItem top="Период бронирования" htmlFor="date">
  <DateRangeInput id="date" aria-label="Период бронирования" />
</FormItem>
```

## Интернационализация (i18n) [#i18n]

> Название месяцев и дней недели определяется исходя из значения `locale` в [`ConfigProvider`](/components/config-provider).

Формат дат и их перевод задаётся с помощью средств браузера [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat).
Тем не менее компонент, в том числе и календарь, имеют большое количество внутренних интерактивных элементов, которые должны иметь
описание. Особенно важно для доступности (a11y), так как большинство подписей зрячему пользователю не видны, но критически важны
пользователям скринридеров.

Ниже приведён список свойств, которые стоит использовать, если требуется перевести компонент на другой язык. Полный список ищите
в таблице свойств компонента ниже.

- `changeDayLabel`;
- `changeMonthLabel`;
- `changeYearLabel`;
- `changeStartDayLabel`;
- `changeStartMonthLabel`;
- `changeStartYearLabel`;
- `changeEndDayLabel`;
- `changeEndMonthLabel`;
- `changeEndYearLabel`;
- `prevMonthLabel`;
- `nextMonthLabel`;
- `clearFieldLabel`;
- `showCalendarLabel`;
- `calendarLabel`.

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

| Свойство | Тип | По умолчанию | Описание |
| --- | --- | --- | --- |
| `accessible` | `boolean` | `true` | **Deprecated**: Since 8.0.0. Будет удалено в 9.0.0.  Включает режим в котором DateRangeInput доступен для ассистивных технологий. В этом режиме: - календарь больше не открывает при фокусе на DateRangeInput; - иконка календаря видна всегда, чтобы пользователи ассистивных технологий могли открыть календарь по клику на иконку; - календарь при открытии получает фокус, клавиатурный фокус зациклен и не выходит за пределы календаря пока календарь не закрыт. |
| `after` | `ReactNode` | `-` | Добавляет иконку справа.  Рекомендации:  - Используйте следующие размеры иконок `12` \| `16` \| `20` \| `24` \| `28`. - Используйте [IconButton](https://vkui.io/components/icon-button), если вам нужна иконка, реагируюущая на нажатие. |
| `afterAlign` | `FieldIconsAlign` | `-` | Вертикальное выравнивание иконки справа. |
| `before` | `ReactNode` | `-` | Добавляет иконку слева.  Рекомендации:  - Используйте следующие размеры иконок `12` \| `16` \| `20` \| `24` \| `28`. - Используйте [IconButton](https://vkui.io/components/icon-button), если вам нужна иконка, реагирующая на нажатие. |
| `beforeAlign` | `FieldIconsAlign` | `-` | Вертикальное выравнивание иконки слева. |
| `calendarLabel` | `string` | `Календарь` | Label для календаря. |
| `calendarPlacement` | `PlacementWithAuto` | `bottom-start` | Расположение календаря относительно поля ввода. |
| `calendarTestsProps` | `CalendarRangeTestsProps` | `-` | Передает атрибуты `data-testid` для интерактивных элементов в календаре. |
| `changeDayLabel` | `string` | `-` | **Deprecated**: Since 7.4.0. Будет удалено в **VKUI v9**.  Использовалось для задания aria-label для контейнера дней в календаре. Теперь этот контейнер является таблицей (с помощью role="grid") и в aria-label рендерится текущий открытый в календаре месяц и год. |
| `changeEndDayLabel` | `string` | `День окончания` | Label для ввода дня конечной даты. Делает доступным для ассистивных технологий. |
| `changeEndMonthLabel` | `string` | `Месяц окончания` | Label для ввода месяца конечной даты. Делает доступным для ассистивных технологий. |
| `changeEndYearLabel` | `string` | `Год окончания` | Label для ввода года конечной даты. Делает доступным для ассистивных технологий. |
| `changeMonthLabel` | `string` | `Месяц` | `aria-label` для селектора месяца. |
| `changeStartDayLabel` | `string` | `День начала` | Label для ввода дня начальной даты. Делает доступным для ассистивных технологий. |
| `changeStartMonthLabel` | `string` | `Месяц начала` | Label для ввода месяца начальной даты. Делает доступным для ассистивных технологий. |
| `changeStartYearLabel` | `string` | `Год начала` | Label для ввода года начальной даты. Делает доступным для ассистивных технологий. |
| `changeYearLabel` | `string` | `Год` | `aria-label` для селектора года. |
| `clearButtonTestId` | `string` | `-` | Передает атрибут `data-testid` для кнопки очистки даты. |
| `clearFieldLabel` | `string` | `Очистить поле` | Label для кнопки очистки. Делает доступным для ассистивных технологий. |
| `closeOnChange` | `boolean` | `true` | Автоматически закрывать календарь при изменениях. |
| `defaultValue` | `DateRangeType \| null` | `-` | Начальный промежуток при монтировании. |
| `disableCalendar` | `boolean` | `false` | Отключение открытия календаря. |
| `disableFocusTrap` | `boolean` | `-` | Позволяет отключить захват фокуса при появлении календаря. |
| `disableFuture` | `boolean` | `-` | Запрещает выбор даты в будущем. Применяется, если не задано `shouldDisableDate`. |
| `disablePast` | `boolean` | `-` | Запрещает выбор даты в прошлом. Применяется, если не заданы `shouldDisableDate` и `disableFuture`. |
| `disablePickers` | `boolean` | `-` | Отключает селекторы выбора месяца/года. |
| `endDateTestsProps` | `DateTestsProps` | `-` | Передает атрибуты `data-testid` для полей ввода конечной даты. |
| `getRootRef` | `Ref<HTMLDivElement>` | `-` |  |
| `mode` | `"default" \| "plain"` | `-` | Режим отображения.  - `default` — показывает фон, обводку и, при наличии, текст-подсказку. - `plain` — показывает только текст-подсказку. |
| `nextMonthIcon` | `ReactNode` | `-` | Кастомная иконка для кнопки следующего месяца. |
| `nextMonthLabel` | `string` | `Следующий месяц` | `aria-label` для кнопки следующего месяца. |
| `onCalendarOpenChanged` | `((opened: boolean) => void)` | `-` | Обработчик изменения состояния открытия календаря. |
| `onChange` | `((value: DateRangeType \| null) => void)` | `-` | Обработчик изменения выбранного промежутка. |
| `prevMonthIcon` | `ReactNode` | `-` | Кастомная иконка для кнопки предыдущего месяца. |
| `prevMonthLabel` | `string` | `Предыдущий месяц` | `aria-label` для кнопки предыдущего месяца. |
| `renderDayContent` | `((day: Date) => ReactNode)` | `-` | Кастомизация отображения содержимого дня. |
| `restoreFocus` | `boolean \| (() => boolean \| HTMLElement)` | `true` | Управление поведением возврата фокуса при закрытии всплывающего окна. |
| `shouldDisableDate` | `((value: Date) => boolean)` | `-` | Функция для проверки запрета выбора даты. |
| `showCalendarButtonTestId` | `string` | `-` | Передает атрибут `data-testid` для кнопки показа календаря. |
| `showCalendarLabel` | `string` | `Показать календарь` | Label для кнопки открытия календаря. Делает доступным для ассистивных технологий. |
| `startDateTestsProps` | `DateTestsProps` | `-` | Передает атрибуты `data-testid` для полей ввода начальной даты. |
| `status` | `"default" \| "error" \| "valid"` | `-` | Статус отображения поля в форме. |
| `value` | `DateRangeType \| null` | `-` | Текущий выбранный промежуток. |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `-` | День недели, с которого начинается неделя. |