---
description: Компонент для поля даты и времени.
tags: forms
---

<Overview group="dates">

# DateInput [tag:component]

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

</Overview>

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

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

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

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

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

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

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

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

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

```jsx
// Неконтролируемое состояние
<DateInput defaultValue={new Date()} />;

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

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

## Состояния

### `disabled`

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

{/* @example-description: `DateInput` в неактивном состоянии с предустановленной датой. */}
<Playground style={{ width: 'fit-content' }}>
  ```jsx
  <DateInput defaultValue={new Date()} disabled />
  ```
</Playground>

## Валидация

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

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

{/* @example-description: Валидационные состояния `DateInput`: ошибка и успешное заполнение. */}
<Playground style={{ width: 'fit-content' }}>
  ```jsx
  <Flex direction="column" gap="m">
    <DateInput status="error" defaultValue={new Date()} />
    <DateInput status="valid" defaultValue={new Date()} />
  </Flex>
  ```
</Playground>

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

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

- `dayFieldTestId` — поле ввода дня;
- `monthFieldTestId` — поле ввода месяца;
- `yearFieldTestId` — поле ввода года;
- `hourFieldTestId` — поле ввода часа;
- `minuteFieldTestId` — поле ввода минут.

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

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

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

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

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

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

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

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

```jsx
<label>
  День рождения
  <DateInput aria-label="День рождения" />
</label>
```

```jsx
<label htmlFor="date"> День рождения</label>
<DateInput id="date" aria-label="День рождения" />
```

```jsx
<FormItem top="День рождения" htmlFor="date">
  <DateInput 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), так как большинство подписей зрячему пользователю не видны, но критически важны
пользователям скринридеров.

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

- `changeHoursLabel`;
- `changeMinutsLabel`;
- `changeDayLabel`;
- `changeMonthLabel`;
- `changeYearLabel`;
- `prevMonthLabel`;
- `nextMonthLabel`;
- `clearFieldLabel`;
- `showCalendarLabel`;
- `calendarLabel`.

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

| Свойство | Тип | По умолчанию | Описание |
| --- | --- | --- | --- |
| `accessible` | `boolean` | `true` | **Deprecated**: Since 8.0.0. Будет удалено в 9.0.0.  Включает режим в котором DateInput доступен для ассистивных технологий. В этом режиме: - календарь больше не открывает при фокусе на DateInput; - иконка календаря видна всегда, чтобы пользователи ассистивных технологий могли открыть календарь по клику на иконку; - календарь при открытии получает фокус, клавиатурный фокус зациклен и не выходит за пределы календаря пока календарь не закрыт. |
| `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` | `Календарь` | `aria-label` для календаря. |
| `calendarPlacement` | `PlacementWithAuto` | `bottom-start` | Расположение календаря относительно поля ввода. |
| `calendarTestsProps` | `CalendarTestsProps` | `-` | Передает атрибуты `data-testid` для интерактивных элементов в календаре. |
| `changeDayLabel` | `string` | `День` | `aria-label` для поля изменения дня. |
| `changeHoursLabel` | `string` | `Час` | Текст выпадающего списка с выбором часов. Делает его доступным для ассистивных технологий. |
| `changeMinutesLabel` | `string` | `Минута` | Текст выпадающего списка с выбором минут. Делает его доступным для ассистивных технологий. |
| `changeMonthLabel` | `string` | `Месяц` | `aria-label` для селектора месяца. |
| `changeYearLabel` | `string` | `Год` | `aria-label` для селектора года. |
| `clearButtonTestId` | `string` | `-` | Передает атрибут `data-testid` для кнопки очистки даты. |
| `clearFieldLabel` | `string` | `Очистить поле` | Label для кнопки очистки. Делает доступным для ассистивных технологий. |
| `closeOnChange` | `boolean` | `true` | Автоматически закрывать календарь при изменениях. |
| `dayFieldTestId` | `string` | `-` | Передает атрибут `data-testid` для поля ввода дня. |
| `defaultValue` | `Date \| null` | `-` | Начальная дата при монтировании. |
| `disableCalendar` | `boolean` | `false` | Отключение открытия календаря. |
| `disableFocusTrap` | `boolean` | `-` | Позволяет отключить захват фокуса при появлении календаря. |
| `disableFuture` | `boolean` | `-` | Запрещает выбор даты в будущем. Применяется, если не задано `shouldDisableDate`. |
| `disablePast` | `boolean` | `-` | Запрещает выбор даты в прошлом. Применяется, если не заданы `shouldDisableDate` и `disableFuture`. |
| `disablePickers` | `boolean` | `-` | Отключает селекторы выбора месяца/года. |
| `DoneButton` | `ComponentType<ButtonProps>` | `-` | Кастомное отображение кнопки `"Done"`. |
| `doneButtonText` | `string` | `-` | Текст отображаемый в кнопке `"Done"`. |
| `enableTime` | `boolean` | `-` | Включает выбор времени. |
| `getRootRef` | `Ref<HTMLDivElement>` | `-` |  |
| `hourFieldTestId` | `string` | `-` | Передает атрибут `data-testid` для поля ввода часа. |
| `maxDateTime` | `Date` | `-` | Максимальные дата и время, которые можно выбрать. Применяется, если не заданы `shouldDisableDate` и `disablePast`/`disableFuture`. |
| `minDateTime` | `Date` | `-` | Минимальные дата и время, которые можно выбрать. Применяется, если не заданы `shouldDisableDate` и `disablePast`/`disableFuture`. |
| `minuteFieldTestId` | `string` | `-` | Передает атрибут `data-testid` для поля ввода минут. |
| `mode` | `"default" \| "plain"` | `-` | Режим отображения.  - `default` — показывает фон, обводку и, при наличии, текст-подсказку. - `plain` — показывает только текст-подсказку. |
| `monthFieldTestId` | `string` | `-` | Передает атрибут `data-testid` для поля ввода месяца. |
| `nextMonthIcon` | `ReactNode` | `-` | Кастомная иконка для кнопки следующего месяца. |
| `nextMonthLabel` | `string` | `Следующий месяц` | `aria-label` для кнопки следующего месяца. |
| `onApply` | `((value?: Date) => void) \| undefined` | `-` | Обработчик нажатия на кнопку `"Done"`. Используется совместно с флагом `enableTime`. |
| `onCalendarOpenChanged` | `((opened: boolean) => void)` | `-` | Обработчик изменения состояния открытия календаря. |
| `onChange` | `((value: Date \| null) => void)` | `-` | Обработчик изменения выбранной даты. |
| `onHeaderChange` | `((value: Date) => void)` | `-` | Обработчик изменения даты в шапке календаря. |
| `onNextMonth` | `(() => void)` | `-` | Нажатие на кнопку переключения на следующий месяц. |
| `onPrevMonth` | `(() => void)` | `-` | Нажатие на кнопку переключения на предыдущий месяц. |
| `prevMonthIcon` | `ReactNode` | `-` | Кастомная иконка для кнопки предыдущего месяца. |
| `prevMonthLabel` | `string` | `Предыдущий месяц` | `aria-label` для кнопки предыдущего месяца. |
| `renderCustomValue` | `((date: Date) => ReactNode) \| undefined` | `-` | Функция для кастомного форматирования отображаемого значения даты. Позволяет переопределить стандартное отображение даты и вернуть собственное представление. |
| `renderDayContent` | `((day: Date) => ReactNode)` | `-` | Кастомизация отображения содержимого дня. |
| `restoreFocus` | `boolean \| (() => boolean \| HTMLElement)` | `true` | Управление поведением возврата фокуса при закрытии всплывающего окна. |
| `shouldDisableDate` | `((value: Date) => boolean)` | `-` | Функция для проверки запрета выбора даты. |
| `showCalendarButtonTestId` | `string` | `-` | Передает атрибут `data-testid` для кнопки показа календаря. |
| `showCalendarLabel` | `string` | `Показать календарь` | Label для кнопки открытия календаря. Делает доступным для ассистивных технологий. |
| `showNeighboringMonth` | `boolean` | `-` | Показывать дни соседних месяцев. |
| `size` | `"s" \| "m"` | `-` | Размер календаря. |
| `status` | `"default" \| "error" \| "valid"` | `-` | Статус отображения поля в форме. |
| `timezone` | `string` | `-` | Часовой пояс для отображения даты. |
| `value` | `Date \| null` | `-` | Текущая выбранная дата. |
| `viewDate` | `Date` | `-` | Дата отображаемого месяца. При использовании обновление даты должно происходить вне компонента. |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `-` | День недели, с которого начинается неделя. |
| `yearFieldTestId` | `string` | `-` | Передает атрибут `data-testid` для поля ввода года. |