# @snack-uikit/calendar

> `npm i @snack-uikit/calendar`

Latest version **1.0.2** (published 2026-09-29) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @snack-uikit/calendar
pnpm add @snack-uikit/calendar
yarn add @snack-uikit/calendar
bun add @snack-uikit/calendar
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2026-09-29 |
| First published | 2023-12-05 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 8 |
| Unpacked size | 437.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 23 |
| Author | Сергей Хлупин |
| Maintainers | yetihead, agrigorii, cloud-ru-tech |

## Links

- npm: https://www.npmjs.com/package/@snack-uikit/calendar
- Repository: https://github.com/cloud-ru-tech/snack-uikit
- Homepage: https://github.com/cloud-ru-tech/snack-uikit/tree/master/packages/calendar
- Issues: https://github.com/cloud-ru-tech/snack-uikit/issues
- npm.io page: https://npm.io/package/@snack-uikit/calendar

## Dependencies (8)

- [weekstart](https://npm.io/package/weekstart.md) ^2.0.0
- [classnames](https://npm.io/package/classnames.md) ^2.5.1
- [uncontrollable](https://npm.io/package/uncontrollable.md) ^8.0.4
- [@snack-uikit/list](https://npm.io/package/@snack-uikit/list.md) ^1.0.1
- [@snack-uikit/icons](https://npm.io/package/@snack-uikit/icons.md) ^1.0.1
- [@snack-uikit/utils](https://npm.io/package/@snack-uikit/utils.md) ^5.0.0
- [@snack-uikit/button](https://npm.io/package/@snack-uikit/button.md) ^1.0.1
- [@snack-uikit/divider](https://npm.io/package/@snack-uikit/divider.md) ^4.0.0

## Recent versions

- 1.0.2 (latest) — 2026-09-29
- 1.0.1-preview-acb79d0b.0 (preview) — 2026-09-21
- 1.0.1 — 2026-09-21
- 1.0.1-preview-b2e4ed46.0 — 2026-09-21
- 1.0.1-preview-27969f64.0 — 2026-09-21
- 1.0.1-preview-fe85442f.0 — 2026-09-18
- 0.14.4 — 2026-09-15
- 0.14.4-preview-620fd545.0 — 2026-09-09
- 0.14.4-preview-fc6b5b87.0 — 2026-08-20
- 0.14.3 — 2026-08-07
- 0.14.3-preview-4e8bfebd.0 — 2026-08-07
- 0.14.3-preview-eff3bc02.0 — 2026-08-03
- 0.14.2 — 2026-07-03
- 0.14.2-preview-74429015.0 — 2026-07-03
- 0.14.2-preview-02d918ac.0 — 2026-07-03
- … 279 more at https://npm.io/package/@snack-uikit/calendar/versions

## README

# Calendar

## Installation
`npm i @snack-uikit/calendar`

[Changelog](./CHANGELOG.md)

## Description

- Пакет `@snack-uikit/calendar` предоставляет компоненты для выбора даты, диапазона дат и времени: календарь (`Calendar`) и отдельный пикер времени (`TimePicker`).
- Компоненты покрывают основные сценарии работы с датой и временем: выбор одной даты, периода, месяца, года или даты с временем, а также точную установку времени по часам, минутам и опционально секундам.
- Оба компонента поддерживают локализацию (язык и формат дат), управление фокусом с клавиатуры и подстройку под размер контейнера через `fitToContainer`, что упрощает их встраивание в сложные интерфейсы.
- Для режима диапазона в календаре доступны пресеты быстрого выбора периода (например, «Сегодня», «Неделя», «Месяц»), которые можно настраивать через проп `presets`.

## Calendar

### Description

- `Calendar` — основной компонент для выбора дат и периодов: он может работать в режимах `date`, `date-range`, `month`, `month-range`, `year-range`, `year` и `date-time` (дата и время).
- Компонент поддерживает как контролируемый (`value` + `onChangeValue`), так и неконтролируемый (`defaultValue`) режимы и умеет подстраиваться под разные размеры через проп `size` (`s`, `m`, `l`).
- С помощью колбека `buildCellProps` можно управлять доступностью и подсветкой отдельных ячеек (например, отключить прошлые даты или выделить праздничные дни), а опция `showHolidays` автоматически раскрашивает выходные.
- Проп `presets` позволяет добавить панель с пресетами для быстрого выбора периода в режиме `date-range`, в том числе с собственным списком вариантов.
- Локаль (`locale`) задаёт язык подписей и первый день недели, при отсутствии явно переданного значения используется язык браузера пользователя.
- Figma: [`Calendar`](https://www.figma.com/file/jtGxAPvFJOMir7V0eQFukN/Snack-UI-Kit-1.1.0?node-id=41%3A27244&mode=design).

### Example

```tsx
import { Calendar } from '@snack-uikit/calendar';

function CalendarExample() {
  return (
    <>
      {/* Выбор одной даты */}
      <Calendar
        mode='date'
        onChangeValue={(selectedDate: Date) => {
          console.log('Selected date:', selectedDate);
        }}
      />

      {/* Выбор периода c пресетами */}
      <Calendar
        mode='date-range'
        presets={{
          enabled: true,
          title: true,
        }}
        onChangeValue={(selectedRange) => {
          console.log('Selected range:', selectedRange);
        }}
      />

      {/* Выбор даты и времени с отображением секунд */}
      <Calendar
        mode='date-time'
        showSeconds
        onChangeValue={(selectedDateTime: Date) => {
          console.log('Selected date and time:', selectedDateTime);
        }}
      />
    </>
  );
}
```

## TimePicker

### Description

- `TimePicker` — компонент для точного выбора времени (часы, минуты и при необходимости секунды) без выбора календарной даты.
- Поддерживает контролируемый и неконтролируемый режимы через пропы `value`, `defaultValue` и `onChangeValue`, а результирующее значение представлено объектом `TimeValue` (`{ hours, minutes, seconds }`).
- Проп `today` позволяет подсветить «текущее» время (например, рабочее время или время на момент открытия) на основании переданной даты.
- Компонент адаптируется под размеры (`size` — `s`, `m`, `l`) и может растягиваться по контейнеру через `fitToContainer`, а также поддерживает управление фокусом (`onFocusLeave`, `navigationStartRef`) для сложных форм и диалогов.
- Figma: [`TimePicker`](https://www.figma.com/file/jtGxAPvFJOMir7V0eQFukN/Snack-UI-Kit-1.1.0?node-id=41%3A27244&mode=design).

### Example

```tsx
import { TimePicker } from '@snack-uikit/calendar';

function TimePickerExample() {
  return (
    <TimePicker
      showSeconds
      onChangeValue={value => {
        if (!value) {
          return;
        }

        const { hours, minutes, seconds } = value;
        console.log(`Selected time: ${hours}:${minutes}:${seconds}`);
      }}
    />
  );
}
```

[//]: DOCUMENTATION_SECTION_START
[//]: THIS_SECTION_IS_AUTOGENERATED_PLEASE_DONT_EDIT_IT
## Calendar
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| mode* | "date" \| "date-time" \| "date-range" \| "month" \| "month-range" \| "year" \| "year-range" | - | Режим работы календаря: <br> - `date` - режим выбора даты <br> - `date-range` - режим выбора периода <br> - `month-range` - режим выбора периода из месяцев <br> - `year-range` - режим выбора периода из лет <br> - `month` - режим выбора месяца <br> - `date-time` - режим выбора даты и времени <br> - `year` - режим выбора года |
| size | enum Size: `"s"`, `"m"`, `"l"` | m | Размер |
| today | `number \| Date` | - | Дата сегодняшнего дня |
| showHolidays | `boolean` | - | Раскрашивает субботу и воскресенье |
| buildCellProps | `(date: Date, viewMode: ViewMode) => { isDisabled?: boolean; isHoliday?: boolean } ;` | - | Колбек установки свойств ячеек календаря. Вызывается на построение каждой ячейки. Принимает два параметра: <br> `Date` - дата ячейки <br> `ViewMode`: <br>  - `month` отображение месяца, каждая ячейка - 1 день <br>  - `year` отображение года, каждая ячейка - 1 месяц <br>  - `decade` отображение декады, каждая ячейка - 1 год <br><br> Колбек должен возвращать объект с полями, отвечающими за отключение и подкраску ячейки. |
| className | `string` | - | CSS-класс контейнера |
| fitToContainer | `boolean` | true | Отключает предустановленный размер, заставляя компонент подстраиваться к размеру контейнра: (width: 100%, height: 100%). |
| style | `CSSProperties` | - | Объект со стилями на контейнер. |
| autofocus | `boolean` | - | Автофокус |
| locale | `Intl.Locale` | Проставляется в соответствие с языком в настройках браузера | Локаль, в соответствие с которой выставляется язык названий и первый день недели |
| onFocusLeave | `(direction: FocusDirection) => void` | - | Колбек потери фокуса. Вызывается со значением `next`, когда фокус покидает компонент, передвигаясь вперед, по клавише `tab`. Со значением `prev` - по клавише стрелки вверх или `shift + tab`. |
| navigationStartRef | `RefObject<{ focus(): void; }>` | - | Ссылка на управление первым элементом навигации |
| presets | `PresetsOptions` | - | Настройки секции с пресетами быстрого выбора периода. Доступны только при mode === 'date-range' и отсутствии buildCellProps (временно PDS-3139) |
| value | `Date \| Range` | - | Выбранное значение.<br> - в режиме date тип `Date` <br> - в режиме date-range тип `Range` (`[Date, Date]`) <br> - в режиме month-range тип `Range` (`[Date, Date]`) <br> - в режиме year-range тип `Range` (`[Date, Date]`) <br> - в режиме month тип `Date` <br> - в режиме date-time тип `Date` <br> - в режиме year тип `Date` |
| defaultValue | `Date \| Range` | - | Значение по-умолчанию для uncontrolled.<br> - в режиме date тип `Date` <br> - в режиме date-range тип `Range` (`[Date, Date]`) <br> - в режиме month-range тип `Range` (`[Date, Date]`) <br> - в режиме year-range тип `Range` (`[Date, Date]`) <br> - в режиме month тип `Date` <br> - в режиме date-time тип `Date` <br> - в режиме year тип `Date` |
| onChangeValue | `((value: Date) => void) \| ((value: Range) => void) \| ((value: Range) => void) \| ((value: Range) => void) \| ((value: Date) => void) \| ((value: Date) => void) \| ((value: Date) => void)` | - | Колбек выбора значения.<br> - в режиме date принимает тип `Date` <br> - в режиме date-range принимает тип `Range` <br> - в режиме month-range принимает тип `Range` <br> - в режиме year-range принимает тип `Range` <br> - в режиме month принимает тип `Date` <br> - в режиме date-time принимает тип `Date` <br> - в режиме year принимает тип `Date` |
| showSeconds | `boolean` | - | Показывать ли секунды (только в режиме date-time) |
## TimePicker
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| value | `TimeValue` | - | Выбранное значение. |
| today | `number \| Date` | - | Дата сегодняшнего дня |
| defaultValue | `TimeValue` | - | Значение по-умолчанию для uncontrolled. |
| onChangeValue | `(value?: TimeValue) => void` | - | Колбек выбора значения |
| showSeconds | `boolean` | true | Показывать ли секунды |
| footerMode | enum TimePickerFooterMode: `"current-time-and-apply"`, `"apply-only"` | current-time-and-apply | Режим футера: кнопка выбора текущего времени («Текущее») и подтверждения выбранного («Применить»), либо только подтверждение («Применить»). |
| size | enum Size: `"s"`, `"m"`, `"l"` | m | Размер |
| className | `string` | - | CSS-класс контейнера |
| fitToContainer | `boolean` | true | Отключает предустановленный размер, заставляя компонент подстраиваться к размеру контейнра: (width: 100%, height: 100%). |
| onFocusLeave | `(direction: FocusDirection) => void` | - | Колбек потери фокуса. Вызывается со значением `next`, когда фокус покидает компонент, передвигаясь вперед, по клавише `tab`. Со значением `prev` - по клавише стрелки вверх или `shift + tab`. |
| navigationStartRef | `RefObject<{ focus(): void; }>` | - | Ссылка на управление первым элементом навигации |


[//]: DOCUMENTATION_SECTION_END

---
_Source: https://npm.io/package/@snack-uikit/calendar · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._