API корня
Calendar — корневой контейнер состояния календарной системы.
| Проп | Тип | По умолчанию |
|---|---|---|
max | string | — |
Самая поздняя доступная для выбора дата в виде строки YYYY-MM-DD. Месяцы и годы после этой даты становятся недоступны. Пикеры дней, месяцев и годов используют её, чтобы отключать или ограничивать навигацию. | ||
min | string | — |
Самая ранняя доступная для выбора дата в виде строки YYYY-MM-DD. Месяцы и годы до этой даты становятся недоступны. Все пикеры учитывают это ограничение при вычислении активных диапазонов. | ||
selection | S | 'single' |
Режим выбора. Определяет форму value, все даты — строки YYYY-MM-DD: 'single' — строка, '', когда ничего не выбрано; 'multiple' — массив строк; 'range' — кортеж [start, end], где start не позже end, а '' обозначает незаданную границу. По умолчанию: 'single' | ||
view | CalendarView | — |
Контролируемый видимый вид: 'day' — дни видимого месяца (CalendarDays); 'month' — месяцы видимого года (CalendarMonths); 'year' — страницы годов (CalendarYears) | ||
value | CalendarValue<S> | — |
Контролируемое значение выбора, форма которого зависит от режима selection. Некорректные или несуществующие даты считаются невыбранными. | ||
defaultValue | CalendarValue<S> | — |
Неконтролируемое начальное значение выбора, форма которого зависит от режима selection. | ||
defaultView | CalendarView | 'day' |
Начальный вид для неконтролируемого использования. По умолчанию: 'day' | ||
disabled | boolean | — |
| Отключает весь календарь: ни одну дату нельзя выбрать, навигация выключена. | ||
disabledDates | CalendarDatesDisabled | — |
Даты, которые нельзя выбрать, в виде строк YYYY-MM-DD: одна дата; массив дат; предикат (date: string) => boolean | ||
onChangeValue | (value: CalendarValue<S>) => void | — |
Вызывается, когда пользователь меняет выбор. Форма значения зависит от режима selection. | ||
onChangeView | (view: CalendarView) => void | — |
| Вызывается при изменении видимого вида. | ||
month | string | — |
Контролируемый видимый месяц — строка YYYY-MM-DD любого дня этого месяца. | ||
defaultMonth | string | — |
Начальный видимый месяц для неконтролируемого использования — строка YYYY-MM-DD любого дня этого месяца. По умолчанию: месяц выбранной даты, иначе текущий месяц | ||
onChangeMonth | (month: string) => void | — |
Вызывается с первым днём видимого месяца в виде строки YYYY-MM-DD, когда видимый месяц меняется (например, при прокрутке или через пикеры месяца и года). Это событие отражает навигацию по виду, а не выбор. | ||
calendar | CalendarSystem | gregorianCalendar |
Календарная система, в которой показывается календарь. Значения остаются днями в формате YYYY-MM-DD. По умолчанию — григорианский календарь. | ||
locale | string | — |
Локаль BCP 47 для названий месяцев и дней и первого дня недели, например de-DE. Применяется ко всем частям календаря и задаёт lang на корне. По умолчанию — локаль среды выполнения, как у Intl. | ||
size | CalendarBaseSize | 'xs' |
Общая шкала размера календаря. Через CalendarBaseContext влияет на вложенные элементы управления: кнопки навигации, триггеры пикеров и подписи дней недели. | ||
variant | CalendarBaseVariant | 'secondary' |
Визуальный вариант календаря. Передаётся через CalendarBaseContext и используется вложенными элементами управления (кнопками, подписями и т. д.) для единообразной стилизации. | ||
compact | boolean | — |
Флаг плотности для более компактных раскладок. При true корневой элемент получает data-compact="true", чтобы стили могли уменьшить отступы, промежутки и высоту элементов управления для более плотного календаря. При false или undefined календарь использует обычные интервалы. | ||
Также принимает все атрибуты <div>.
API дочерних частей
Публичные дочерние части делятся на четыре группы:
- части заголовка и навигации
- кнопки переключения видов
- виды
- шаблоны ячеек
| Часть | Примечания |
|---|---|
CalendarHeader, CalendarContent | Обёртки разметки. |
CalendarPrevButton, CalendarNextButton | Предыдущий / следующий месяц в днях, предыдущая / следующая страница лет в годах; скрыты в виде месяцев. Показывают шеврон, если не переданы children. |
CalendarViewButtonGroup | Группирует кнопки видов. |
CalendarViewButton | Переключает этот вид, aria-pressed, пока он показан. |
CalendarMonthLabel, CalendarYearLabel | Видимые месяц и год в локали корня. |
CalendarDays | Вид дней; содержит CalendarWeekdays и CalendarWeeks. |
CalendarWeekdays | Названия дней недели в локали корня. |
CalendarWeeks | Сетка дней с переключением свайпом. |
CalendarMonths | Месяцы видимого года. |
CalendarYears | Страницы лет с переключением свайпом. |
CalendarWeekday | Шаблон дня недели; без дочерних элементов показывает название дня недели. |
CalendarDay, CalendarMonth, CalendarYear | Шаблоны ячеек; без дочерних элементов показывают отформатированную подпись. |
Виды принимают только HTML-атрибуты и параметры отображения. Месяц, выбор, отключённые даты, локаль, календарная система, размер и вариант берутся из корня Calendar.
Дочерние элементы CalendarWeekdays, CalendarWeeks, CalendarMonths и CalendarYears — это шаблон, который рендерится по одному разу на день недели или ячейку. Они обязательны, обычно это <CalendarWeekday />, <CalendarDay />, <CalendarMonth /> или <CalendarYear />.
Дочерние части следует рассматривать как одну согласованную систему, а не как отдельные виджеты.
CalendarHeader
Также принимает все атрибуты <div>.
CalendarPrevButton
| Проп | Тип | По умолчанию |
|---|---|---|
size | IconButtonSize | — |
| Размер контейнера кнопки. Управляет отступами и общей кликабельной областью. | ||
asChild | boolean | — |
Если true, рендерит кнопку как дочерний компонент через Slot (например, из Radix UI). Включает полиморфный рендер — полезно, чтобы кнопка работала как ссылка или собственный тег. | ||
variant | ButtonBaseVariant | — |
| Определяет визуальный стиль кнопки: цветовую схему и акцент. | ||
appearance | ButtonBaseAppearance | — |
| Настраивает структурный внешний вид кнопки (фон, рамка и т. д.). | ||
disabled | boolean | — |
Отключает кнопку при true. Запрещает взаимодействие и применяет визуальное отключённое состояние. Не применяется с asChild: отключённым состоянием владеет дочерний элемент, например через aria-disabled или ссылку без href. | ||
className | string | — |
| Необязательный собственный CSS-класс для элемента кнопки. Полезен для переопределений дизайн-системы или локальных стилей. | ||
children | ReactNode | — |
| Содержимое кнопки — текст, иконка или любой React-узел. | ||
ref | Ref<HTMLButtonElement> | — |
Ref, передаваемый на нативный элемент <button>. Даёт прямой доступ к DOM для управления фокусом или измерений. | ||
Также принимает все атрибуты <button>.
CalendarNextButton
| Проп | Тип | По умолчанию |
|---|---|---|
size | IconButtonSize | — |
| Размер контейнера кнопки. Управляет отступами и общей кликабельной областью. | ||
asChild | boolean | — |
Если true, рендерит кнопку как дочерний компонент через Slot (например, из Radix UI). Включает полиморфный рендер — полезно, чтобы кнопка работала как ссылка или собственный тег. | ||
variant | ButtonBaseVariant | — |
| Определяет визуальный стиль кнопки: цветовую схему и акцент. | ||
appearance | ButtonBaseAppearance | — |
| Настраивает структурный внешний вид кнопки (фон, рамка и т. д.). | ||
disabled | boolean | — |
Отключает кнопку при true. Запрещает взаимодействие и применяет визуальное отключённое состояние. Не применяется с asChild: отключённым состоянием владеет дочерний элемент, например через aria-disabled или ссылку без href. | ||
className | string | — |
| Необязательный собственный CSS-класс для элемента кнопки. Полезен для переопределений дизайн-системы или локальных стилей. | ||
children | ReactNode | — |
| Содержимое кнопки — текст, иконка или любой React-узел. | ||
ref | Ref<HTMLButtonElement> | — |
Ref, передаваемый на нативный элемент <button>. Даёт прямой доступ к DOM для управления фокусом или измерений. | ||
Также принимает все атрибуты <button>.
CalendarViewButtonGroup
Также принимает все атрибуты <div>.
CalendarViewButton
| Проп | Тип | По умолчанию |
|---|---|---|
viewобязательный | Exclude<CalendarView, 'day'> | — |
Вид, который открывает кнопка: 'month' для CalendarMonths, 'year' для CalendarYears. Повторное нажатие возвращает к дням. | ||
asChild | boolean | — |
Если true, рендерит кнопку как дочерний компонент через Slot (например, из Radix UI). Включает полиморфный рендер — полезно, чтобы кнопка работала как ссылка или собственный тег. | ||
size | ButtonSize | — |
| Определяет размер кнопки. Влияет на отступы, размер шрифта и общие габариты. | ||
fullWidth | boolean | — |
| Если true, кнопка растягивается на всю ширину контейнера. | ||
variant | ButtonBaseVariant | — |
| Определяет визуальный стиль кнопки: цветовую схему и акцент. | ||
appearance | ButtonBaseAppearance | — |
| Настраивает структурный внешний вид кнопки (фон, рамка и т. д.). | ||
disabled | boolean | — |
Отключает кнопку при true. Запрещает взаимодействие и применяет визуальное отключённое состояние. Не применяется с asChild: отключённым состоянием владеет дочерний элемент, например через aria-disabled или ссылку без href. | ||
className | string | — |
| Необязательный собственный CSS-класс для элемента кнопки. Полезен для переопределений дизайн-системы или локальных стилей. | ||
children | ReactNode | — |
| Содержимое кнопки — текст, иконка или любой React-узел. | ||
ref | Ref<HTMLButtonElement> | — |
Ref, передаваемый на нативный элемент <button>. Даёт прямой доступ к DOM для управления фокусом или измерений. | ||
Также принимает все атрибуты <button>.
CalendarMonthLabel
| Проп | Тип | По умолчанию |
|---|---|---|
format | Intl.DateTimeFormatOptions['month'] | 'long' |
Формат отображения месяца (из Intl.DateTimeFormatOptions). Определяет, как выглядит название месяца. Возможные значения: "long" → January (по умолчанию); "short" → Jan; "narrow" → J | ||
CalendarYearLabel
| Проп | Тип | По умолчанию |
|---|---|---|
format | Intl.DateTimeFormatOptions['year'] | 'numeric' |
Формат отображаемого года (из Intl.DateTimeFormatOptions). Возможные значения: "numeric" → 2026; "2-digit" → 26. Обычно по умолчанию "numeric". | ||
CalendarContent
Также принимает все атрибуты <div>.
CalendarDays
Также принимает все атрибуты <div>.
CalendarWeekdays
| Проп | Тип | По умолчанию |
|---|---|---|
format | Intl.DateTimeFormatOptions['weekday'] | 'short' |
Формат названий дней недели (Intl.DateTimeFormat weekday). | ||
childrenобязательный | ReactNode | — |
Шаблон, который рендерится один раз для каждого дня недели, обычно <CalendarWeekday />. День недели читается через useCalendarWeekdayContext(). | ||
Также принимает все атрибуты <div>.
CalendarWeekday
| Проп | Тип | По умолчанию |
|---|---|---|
size | TextSize | — |
| Визуальный размер текста, обычно соответствует типографической шкале дизайн-системы. | ||
asChild | boolean | — |
Если true, рендерит текст как дочерний компонент через Slot. Полезно для совместимости с нативными элементами или другими компонентами. | ||
fontWeight | 400 | 500 | 600 | 700 | 900 | — |
| Насыщенность шрифта текста. Распространённые значения: 400: обычный; 500: средний; 600: полужирный; 700: жирный; 900: сверхжирный | ||
ref | Ref<HTMLSpanElement> | — |
Ref на нижележащий <span> или элемент в слоте. Полезен для измерений, фокуса или работы с DOM. | ||
Также принимает все атрибуты <span>.
CalendarWeeks
| Проп | Тип | По умолчанию |
|---|---|---|
childrenобязательный | ReactNode | — |
Шаблон ячейки дня, рендерится один раз для каждого дня видимых месяцев. День читается через useCalendarDayContext(); обычно <CalendarDay />. | ||
format | Intl.DateTimeFormatOptions['day'] | "numeric" |
Формат номеров дней (Intl.DateTimeFormat day). | ||
includeOverflowDays | boolean | false |
| Заполняют ли дни предыдущего и следующего месяцев пустые ячейки. | ||
start | number | -2 |
| Начальный индекс для генерации исходной последовательности страниц. Служит логической точкой отсчёта для скользящего окна индексов. | ||
size | number | 5 |
| Количество сегментов индексов, отрендеренных одновременно. Определяет размер виртуального «окна», по которому скроллер сдвигается при навигации влево или вправо. | ||
startDir | -1 | 1 | 1 |
Направление, в котором растёт начальная последовательность индексов. 1 — индексы растут вправо (0, 1, 2…); -1 — индексы убывают вправо (0, -1, -2…). Управляет порядком роста начального массива индексов. | ||
shift | number | 2 |
| Количество страниц, добавляемых, когда прокрутка доходит до конца окна, чтобы быстрый свайп продолжался. Когда прокрутка останавливается, окно заново центрируется на странице привязки. | ||
index | number | — |
| Управляет текущим активным логическим индексом. Если задан, скроллер держит этот индекс в области видимости: прокручивает к нему, если это возможно, или при необходимости перестраивает окно. | ||
preserveScroll | boolean | true |
Сохраняет текущий привязанный элемент после изменения содержимого (например, когда страницы добавляются в начало или конец). Если true, скроллер восстановит тот же индекс привязки через мгновенный scrollIntoView. | ||
onOffset | (value: number) => void | — |
Вызывается, когда окно растёт у края. -1 — прокрутка остановилась на первой странице (левый/верхний край); +1 — прокрутка дошла до конца (правый/нижний край). Полезно для бесконечной подгрузки: добавляйте страницы в конец или в начало в зависимости от направления. | ||
ref | Ref<HTMLDivElement> | — |
| Ref на элемент скроллера. | ||
defaultIndex | number | — |
| Начальный индекс элемента, к которому выполняется привязка при монтировании. | ||
onScrollSnapChange | (element: HTMLElement, index: number) => void | — |
| Вызывается, когда операция прокрутки с привязкой полностью завершена и скроллер остановился на новом индексе привязки. Колбэк вызывается после завершения всех анимаций прокрутки и привязки, когда активная позиция привязки считается стабильной. | ||
onScrollSnapChanging | (element: HTMLElement, index: number) => void | — |
| Вызывается, пока операция прокрутки с привязкой идёт и активный индекс привязки ещё меняется. Колбэк может вызываться несколько раз за одну прокрутку или свайп, пока скроллер приближается к конечной позиции привязки. Полезен для оптимистичных обновлений интерфейса, превью или синхронизации промежуточного состояния во время прокрутки. | ||
Также принимает все атрибуты <div>.
CalendarDay
| Проп | Тип | По умолчанию |
|---|---|---|
size | DataGridPickerSize | — |
| Управляет визуальным размером элемента. Полезно для адаптации пикера к компактным или крупным раскладкам. | ||
range | DataGridPickerItemRangePosition | — |
Необязательный визуальный индикатор положения ячейки в диапазоне. Одно из: "start" | "between" | "end". Если не задан, компонент вычисляет его автоматически по контексту выбора. | ||
variant | DataGridPickerVariant | — |
| Предустановка внешнего вида пикера. | ||
disabled | boolean | — |
| Отключает выбор кликом и с клавиатуры. Переопределяет значение из корневого DataGrid | ||
ref | Ref<HTMLDivElement> | — |
Внешний ref на корневой элемент ячейки. Объединяется с внутренней регистрацией itemRef([row, col], key), если ячейка не исключена. | ||
asChild | boolean | false |
Если true, рендерит дочерние элементы через Slot и передаёт пропсы и ref дочернему элементу вместо использования нативного <div>. | ||
excluded | boolean | — |
| Исключает ячейки из обхода фокусом. Переопределяет значение из корневого DataGrid | ||
Также принимает все атрибуты <div>.
CalendarMonths
| Проп | Тип | По умолчанию |
|---|---|---|
childrenобязательный | ReactNode | — |
Шаблон ячейки месяца, рендерится один раз для каждого месяца видимого года. Месяц читается через useCalendarMonthContext(); обычно <CalendarMonth />. | ||
cols | number | 3 |
| Количество столбцов сетки месяцев. | ||
format | Intl.DateTimeFormatOptions['month'] | "long" |
Формат названий месяцев (Intl.DateTimeFormat month). | ||
Также принимает все атрибуты <div>.
CalendarMonth
| Проп | Тип | По умолчанию |
|---|---|---|
size | DataGridPickerSize | — |
| Управляет визуальным размером элемента. Полезно для адаптации пикера к компактным или крупным раскладкам. | ||
range | DataGridPickerItemRangePosition | — |
Необязательный визуальный индикатор положения ячейки в диапазоне. Одно из: "start" | "between" | "end". Если не задан, компонент вычисляет его автоматически по контексту выбора. | ||
variant | DataGridPickerVariant | — |
| Предустановка внешнего вида пикера. | ||
disabled | boolean | — |
| Отключает выбор кликом и с клавиатуры. Переопределяет значение из корневого DataGrid | ||
ref | Ref<HTMLDivElement> | — |
Внешний ref на корневой элемент ячейки. Объединяется с внутренней регистрацией itemRef([row, col], key), если ячейка не исключена. | ||
asChild | boolean | false |
Если true, рендерит дочерние элементы через Slot и передаёт пропсы и ref дочернему элементу вместо использования нативного <div>. | ||
excluded | boolean | — |
| Исключает ячейки из обхода фокусом. Переопределяет значение из корневого DataGrid | ||
Также принимает все атрибуты <div>.
CalendarYears
| Проп | Тип | По умолчанию |
|---|---|---|
childrenобязательный | ReactNode | — |
Шаблон ячейки года, рендерится один раз для каждого года видимых страниц. Год читается через useCalendarYearContext(); обычно <CalendarYear />. | ||
format | Intl.DateTimeFormatOptions['year'] | "numeric" |
Формат годов (Intl.DateTimeFormat year). | ||
Также принимает все атрибуты <div>.
CalendarYear
| Проп | Тип | По умолчанию |
|---|---|---|
size | DataGridPickerSize | — |
| Управляет визуальным размером элемента. Полезно для адаптации пикера к компактным или крупным раскладкам. | ||
range | DataGridPickerItemRangePosition | — |
Необязательный визуальный индикатор положения ячейки в диапазоне. Одно из: "start" | "between" | "end". Если не задан, компонент вычисляет его автоматически по контексту выбора. | ||
variant | DataGridPickerVariant | — |
| Предустановка внешнего вида пикера. | ||
disabled | boolean | — |
| Отключает выбор кликом и с клавиатуры. Переопределяет значение из корневого DataGrid | ||
ref | Ref<HTMLDivElement> | — |
Внешний ref на корневой элемент ячейки. Объединяется с внутренней регистрацией itemRef([row, col], key), если ячейка не исключена. | ||
asChild | boolean | false |
Если true, рендерит дочерние элементы через Slot и передаёт пропсы и ref дочернему элементу вместо использования нативного <div>. | ||
excluded | boolean | — |
| Исключает ячейки из обхода фокусом. Переопределяет значение из корневого DataGrid | ||
Также принимает все атрибуты <div>.
Хуки
useCalendarContext
Продвинутый хук для пользовательских частей. Отдаёт состояние корня, включая view, month, locale, calendar, toggleView(view), closeView(), prev() и next().
useCalendarWeekdayContext
День недели из окружающего шаблона CalendarWeekdays:
| Поле | Тип | Примечания |
|---|---|---|
col | number | Индекс колонки в строке. |
weekday | number | День недели как в Date#getDay(): 0 — воскресенье, 6 — суббота. |
label | string | Название дня недели в локали корня. |
useCalendarDayContext
День из окружающего шаблона CalendarWeeks:
| Поле | Тип | Примечания |
|---|---|---|
col | number | Индекс колонки в неделе. |
date | string | undefined | День в формате ISO YYYY-MM-DD; undefined для пустой ячейки соседнего месяца. |
fields | CalendarDateFields | undefined | День в календарной системе: { era?, year, month, day }. |
label | string | Отформатированный номер дня в локали и календарной системе. |
inMonth | boolean | Принадлежит ли день отрендеренному месяцу. |
useCalendarMonthContext / useCalendarYearContext
Месяц или год из окружающего шаблона CalendarMonths / CalendarYears: col, date (первый день месяца или года, ISO), fields и label.
Берите номер дня, месяца или года из label или fields, а не из ISO-строки date: в негригорианских календарях они различаются.
Типы
| Тип | Определение | Примечания |
|---|---|---|
CalendarProps | Тип пропсов корня | Основная поверхность интеграции. |
CalendarView | объединение видов | 'day', 'month' или 'year'. |
CalendarSelection | объединение режимов выбора | single, multiple или range. |
CalendarValue | значение выбора по режиму | Строка YYYY-MM-DD, кортеж [start, end] (start никогда не позже end) или массив строк. |
CalendarDatesDisabled | контракт отключённых дат | Строка YYYY-MM-DD, массив строк или предикат (date: string) => boolean. |
Модель состояния
- Видимая дата и состояние выбора хранятся в корне.
- Режим выбора меняет ожидаемую форму значения.
- Виды согласованы вокруг одного состояния корня.
viewопределяет, что видно — дни, месяцы или годы, — и управляет кнопками «назад» и «вперёд».localeиcalendar— пропсы корня, которые читает каждая часть; по умолчанию используются локаль среды выполнения и григорианский календарь.
Заметки по интеграции
- Передавайте в слой компонентов ISO-строки
YYYY-MM-DDи храните значение в этом виде; в другие форматы преобразуйте на уровне приложения. calendarменяет то, как дни группируются и подписываются, но не значение. См. Даты и календарные системы.- Тщательно перепроверяйте пользовательские шаблоны ячеек и ячейки соседних месяцев.
- Используйте низкоуровневые
DayPicker,MonthPickerиYearPicker, только когда полная композицияCalendarне нужна. - Обращайтесь к
DayPicker,MonthPicker,YearPickerилиCalendarBaseтолько при создании собственного поведения семейства календарей, а не в первую очередь для обычного выбора даты.