Выбор периода

Date range picker — поле формы для периода, например поездки или отчётного окна. Начало и конец вводят с клавиатуры или выбирают в календаре на два месяца.

Стабильный

Figma

Обзор

Использование

API

Доступность

<tk-date-range-picker label="Stay dates" helper="For example, 27 3 2026"
  start-name="check-in" end-name="check-out"
  min="2026-01-01" max="2026-12-31"></tk-date-range-picker>

У поля периода свои подпись, подсказка и ошибка; не оборачивайте его в Field.

Анатомия

Часть	Что это
`tk-date-range-picker`	сам элемент
подпись	называет пару дат, например «Stay dates»; звёздочка при `required`
подсказка	необязательный текст под подписью
part `field`	рамка с обоими полями
part `input`	поля начала и конца с именами «Start date» и «End date»; в них всегда можно печатать
разделитель	«–» между полями
кнопка очистки	«Clear dates»; появляется, когда есть значение
кнопка календаря	открывает календарь
ошибка	текст под рамкой
part `popover`	панель с пресетами и Calendar на два месяца

У каждой даты своё поле и своё имя, поэтому скринридер отличает начало от конца. Не заменяйте их одним текстовым полем «начало – конец».

Размеры

<tk-date-range-picker label="Report period" size="large"
  start="2026-03-01" end="2026-03-31"></tk-date-range-picker>

`size`	Высота	Отступы по бокам	Текст значения
`medium` (по умолчанию)	32px	`space-8` / `space-4`	Body Small (14/20)
`large`	36px	`space-10` / `space-4`	Body Medium (16/24)

Календарь одного размера при любом размере поля.

Состояния

<tk-date-range-picker label="Billing period" disabled
  start="2026-02-01" end="2026-02-28"></tk-date-range-picker>
<tk-date-range-picker label="Trip dates" required
  error="Enter a start and end date"></tk-date-range-picker>

При наведении рамка не меняется. Фокус в любом из полей окрашивает рамку и утолщает её внутрь. При ошибке рамка остаётся красной, даже в фокусе.

readonly: даты можно выделить и скопировать; кнопки не работают.
disabled: ничего не работает, даты не уходят с формой.
error: ваш текст под рамкой. Он заменяет любое сообщение, которое пишет само поле.

Выбор периода

Календарь открывает его кнопка или Down в любом из полей; он открывается на дате начала или на сегодня.
Первый выбор задаёт начало, календарь остаётся открытым. При наведении виден период.
Второй выбор задаёт конец, вызывает change и закрывает календарь.
Выбор дня раньше начала сдвигает начало.
Esc, клик снаружи или Tab закрывают календарь и отбрасывают недовыбранный период. Прежний период остаётся.
В любое поле можно печатать в любой момент, в тех же форматах, что у Date picker. Текст разбирается по Enter или когда фокус уходит из поля.

Пресеты

Положите кнопки в слот presets; они встанут слева от календаря. Кнопка с data-start и data-end (даты ISO) выбирает этот период и закрывает календарь без всякого скрипта.

March

2026

<tk-date-range-picker label="Report period" start-name="from" end-name="to">
  <tk-button slot="presets" variant="ghost" size="small"
    data-start="2026-03-01" data-end="2026-03-31">March</tk-button>
  <tk-button slot="presets" variant="ghost" size="small"
    data-start="2026-01-01" data-end="2026-12-31">2026</tk-button>
</tk-date-range-picker>

Пресеты вроде «Последние 7 дней» зависят от сегодняшней даты, поэтому их пишете вы: посчитайте даты в своём коде или вызовите selectRange().

Когда использовать

Date range picker — для периода: проживание, бронирование, отчётное окно.
Для одной даты берите Date picker. Не связывайте два поля даты в период.
Calendar с mode="range" — когда сетка должна быть видна на странице постоянно.
Для времени — Time picker.

Текст

Назовите период в подписи: «Даты проживания», «Отчётный период».
Переименуйте поля, если так понятнее: start-label="Check-in", end-label="Check-out".
Дайте формат в подсказке с примером: «Например, 27 3 2026».

Часть ошибок поле пишет само. Остальные задайте через error в том же стиле:

Проблема	Текст ошибки
пусто, а поле обязательное	«Введите дату начала и конца»
такой даты нет	«Start date must be a real date» (пишет поле)
конец раньше начала	«End date must be the same as or after the start date» (пишет поле)
вне `min` / `max`	«Введите даты не раньше 1 янв. 2026»

Подробнее в Errors.

Можно / нельзя

✅ Можно	❌ Нельзя
Брать одно поле периода для периода	Связывать два поля даты вручную
Называть поля под задачу: «Check-in», «Check-out»	Делать одно текстовое поле «начало – конец»
Давать формат в `helper`	Оставлять формат угадывать
Задавать `min` и `max`	Разрешать любую дату любого года
Давать вводить любую из дат с клавиатуры	Оставлять календарь единственным способом ввода

Calendar: сетка периода внутри.
Date picker: одна дата.
Time picker: время.
Input: рамка, общая с этими полями.

API

Атрибуты

Атрибут	Тип	По умолчанию	Что делает
`label`	строка	`''`	видимое имя пары дат; обязателен
`label-hidden`	boolean	`false`	прячет подпись, но оставляет её именем
`start-label` / `end-label`	строка	`Start date` / `End date`	имена двух полей
`helper`	строка	—	подсказка под подписью
`error`	строка	—	текст ошибки под рамкой
`start` / `end`	дата ISO (`yyyy-mm-dd`)	`''`	период
`start-name` / `end-name`	строка	—	имена полей в форме; каждая дата отправляется отдельно
`min` / `max`	дата ISO	—	допустимые даты; даты вне их блокируют отправку
`visible-months`	`1`–`3`	`2`	сколько месяцев в календаре
`week-start`	`1`–`7`	`1`	первый день недели, от понедельника до воскресенья
`required`	boolean	`false`	для отправки нужны обе даты; добавляет звёздочку
`readonly`	boolean	`false`	можно выделить и скопировать; кнопки не работают
`disabled`	boolean	`false`	не получает фокус, не уходит с формой
`size`	`medium` \| `large`	`medium`	высота 32 / 36px

Слоты

Слот	Содержимое
`presets`	кнопки с `data-start` и `data-end` рядом с календарём

События

change срабатывает, когда период меняется: готовый период, пресет, введённая дата или очистка. Не срабатывает на первый из двух выборов и когда вы задаёте start или end из кода. Сброс формы возвращает первый период.

Методы

selectRange(start, end): задаёт обе даты и закрывает календарь.
clear(): очищает обе даты.

Оба вызывают change, если период изменился.

CSS

::part(field): рамка поля.
::part(input): оба поля.
::part(popover): панель календаря.

Токены

Рамка берёт токены Input, кнопки — токены Date picker, сетка — токены Calendar. Свои у поля периода:

Часть	Токены
подпись	`text/default`, Label Medium; звёздочка `text/secondary`
подсказка	`text/secondary`, Body Small
подпись и подсказка, неактивные	`text/disabled`
колонка пресетов	отступ `space-8`, промежуток `space-4`, разделитель `border/subtle`
всплывающая панель	`surface/raised` + `shadow-2`, `radius-16`

Значения для каждой темы: Color.

Доступность

Встроено:

Два именованных поля в группе, которую называет label.
Кнопка календаря называется «Choose date range», а после выбора — «Change dates, 5 Mar 2026 to 20 Mar 2026, 16 days».
Открытие переводит фокус в календарь; поля остаются доступными, пока он открыт.
Календарь объявляет концы периода и готовый период с числом дней.
Пустая обязательная дата, неразборчивая дата, конец раньше начала или дата вне границ блокируют отправку и переводят фокус в поле.

Ваша часть:

Задайте label и переименуйте поля, если «Start date» и «End date» не подходят.
Положите пример формата в helper.
Задайте min и max под даты, которые имеют смысл.

Клавиша	Действие
`Tab`	поле начала, поле конца, кнопка очистки, кнопка календаря
`Down` / `Alt` + `Down`	открывает календарь и переводит в него фокус
`Enter`	разбирает введённую дату; если обе даты есть и календарь закрыт, отправляет форму
`Esc`	закрывает календарь и отбрасывает недовыбранный период

Клавиши внутри календаря: Calendar.

Пределы контраста

Рамка поля: 1.33:1 в светлой теме и 2.00:1 в тёмной, ниже минимума 3:1; 4.22:1 в высококонтрастной. Всегда показывайте подпись.
Полоса периода: полоса между концами бледная во всех темах. Выбор передают залитые концы и объявление.

Анатомия

Размеры

Состояния

Выбор периода

Пресеты

Когда использовать

Текст

Можно / нельзя

Связанные

API

Атрибуты

Слоты

События

Методы

CSS

Токены

Доступность

Пределы контраста