Forms

Stable - @kikita-labs/ui v2.0.0

Calendar

Inline month grid for single-date selection; kui-calendar-range selects a start and end pair.

Import

Calendar is a standalone component with optional locale provider helpers.

calendar.ts
import {
  KuiCalendar,
  type KuiCalendarMessages,
  provideKikitaUi,
  provideKuiLocale,
} from '@kikita-labs/ui';

Usage

Open in Playground

Bind value with a signal and keep Date objects in component state.

SunMonTueWedThuFriSat
2026-07-14
SunMonTueWedThuFriSat
<div class="basic-calendar-example">
  <kui-calendar [(value)]="selectedDate" [minDate]="minDate" showFooter />

  <kui-calendar size="sm" flat [(value)]="selectedDate" />
</div>

States and composition

The installed API covers disabled dates, bounds, the footer, a hidden navigation control and popover-friendly flat mode.

SunMonTueWedThuFriSat
SunMonTueWedThuFriSat
<div class="calendar-states-example">
  <kui-calendar
    [(value)]="selectedDate"
    [minDate]="minDate"
    [maxDate]="maxDate"
    [disabledDates]="holidays"
  />

  <kui-calendar [(value)]="selectedDate" [disabledDates]="isWeekend" [showWeekend]="false" />
</div>
  • Use kui-calendar-range (KuiCalendarRange) when the value is a KuiDateRange; kui-calendar selects a single date.
  • minDate, maxDate and disabledDates block days; disabledDates takes dates or a predicate. minDate and maxDate are models, so a paired date picker can wire them for you.
  • Use flat inside kui-dropdown so panel chrome is not doubled, and size="sm" for tight sidebars. The width is --kui-calendar-width (296px).
  • viewDate (a first-of-month date, two-way) moves the displayed month from the outside. showPrevNav and showNextNav hide one navigation control for two linked calendars a month apart.
  • Placed next to input[kuiDatePicker] in the same kui-field, the directive wires value, viewDate and the bounds automatically; see Date Picker.

Locale and messages

Month and weekday names, the heading order, the first day of the week and the weekend come from Intl for the locale of the nearest i18n level, with no bundled locale data.

日月火水木金土
MoDiMiDoFrSaSo
2026-10-03
<div class="calendar-locale-example">
  <kui-calendar locale="ja-JP" size="sm" [(value)]="selectedDate" />

  <kui-calendar
    locale="de-DE"
    size="sm"
    showFooter
    [messages]="messages"
    [(value)]="selectedDate"
  />
</div>
  • The locale starts from the app-wide KUI_LOCALE (the browser language, or the request's Accept-Language on the server), falls back to en-US, and is overridden per instance by the locale input.
  • Day buttons are named with the full localized date, for example Saturday, October 3, 2026, and the weekend follows the locale (a Friday and Saturday weekend in he-IL).
  • messages overrides the calendar texts for one instance; it wins over scoped and root messages. Names use the Gregorian calendar and Latin digits. 
import { provideKikitaUi } from '@kikita-labs/ui';

provideKikitaUi({ locale: 'ja-JP' });

Provider defaults

Set defaults.calendar once for the application or for a subtree. Each option resolves as local input > defaults.calendar.<option> > built-in default.

import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        calendar: {
          /* options below */
        },
      },
    }),
  ],
};
NameTypeDefaultDescription
size'md' | 'sm' — Calendar size. Takes precedence over the global defaults.size.
flatboolean — Strips the calendar's own background, border and padding.
showWeekendboolean — Shows Saturday and Sunday in a muted colour.
showFooterboolean — Shows the footer with the current value and the "Today" shortcut.
showPrevNavboolean — Shows the "previous" navigation control in the header.
showNextNavboolean — Shows the "next" navigation control in the header.
previousIconKuiIconGlyph — Icon of the previous control. Takes precedence over defaults.icons.previous. See Structural Icons.
nextIconKuiIconGlyph — Icon of the next control. Takes precedence over defaults.icons.next. See Structural Icons.

Theming tokens

Set any of these on the component or an ancestor to restyle one part. Each token is optional: when it is not set, the part uses the role or scale token in the default column.

NameTypeDefaultDescription
--kui-calendar-bgCSS custom property--kui-color-surfaceBackground
--kui-calendar-borderCSS custom property--kui-color-borderBorder color
--kui-calendar-colorCSS custom property--kui-color-textColor
--kui-calendar-title-colorCSS custom property--kui-color-textTitle color
--kui-calendar-day-colorCSS custom property--kui-color-textDay color
--kui-calendar-day-focus-ring-colorCSS custom property--kui-color-focusDay focus ring color
--kui-calendar-day-color-mutedCSS custom property--kui-color-text-secondaryDay color, muted
--kui-calendar-day-color-weekendCSS custom property--kui-color-text-secondaryDay color, weekend
--kui-calendar-day-bg-selectedCSS custom property--kui-color-primary-fillDay background, selected
--kui-calendar-day-color-selectedCSS custom property--kui-color-primary-on-fillDay color, selected
--kui-calendar-day-color-range-middleCSS custom property--kui-color-primary-soft-textDay color, range middle
--kui-calendar-day-bg-range-startCSS custom property--kui-color-primary-fillDay background, range start
--kui-calendar-day-color-range-startCSS custom property--kui-color-primary-on-fillDay color, range start
--kui-calendar-day-bg-range-endCSS custom property--kui-color-primary-fillDay background, range end
--kui-calendar-day-color-range-endCSS custom property--kui-color-primary-on-fillDay color, range end
--kui-calendar-day-bg-range-edge-hoverCSS custom property--kui-color-primary-fill-hoverDay background, range edge hover
--kui-calendar-day-bg-range-middle-hoverCSS custom property?Day background, range middle hover
--kui-calendar-day-bg-selected-hoverCSS custom property--kui-color-primary-fill-hoverDay background, selected hover
--kui-calendar-value-colorCSS custom property--kui-color-text-secondaryValue color
--kui-calendar-picker-cell-colorCSS custom property--kui-color-textPicker cell color
--kui-calendar-picker-cell-focus-ring-colorCSS custom property--kui-color-focusPicker cell focus ring color
--kui-calendar-picker-cell-bg-activeCSS custom property--kui-color-primary-fillPicker cell background, active
--kui-calendar-picker-cell-color-activeCSS custom property--kui-color-primary-on-fillPicker cell color, active
--kui-calendar-picker-cell-color-mutedCSS custom property--kui-color-text-secondaryPicker cell color, muted
NameTypeDefaultDescription
--kui-calendar-radiusCSS custom property--kui-radius-lgCorner radius
--kui-calendar-paddingCSS custom property--kui-space-4Padding
--kui-calendar-title-font-sizeCSS custom property--kui-text-sm-sizeTitle font size
--kui-calendar-title-padding-inlineCSS custom property--kui-space-2Title padding, inline
--kui-calendar-nav-spacer-sizeCSS custom property--kui-control-height-xsNav spacer size
--kui-calendar-weekday-font-sizeCSS custom property--kui-text-xs-sizeWeekday font size
--kui-calendar-weekday-padding-bottomCSS custom property--kui-space-2Weekday padding, bottom
--kui-calendar-day-font-sizeCSS custom property--kui-text-sm-sizeDay font size
--kui-calendar-footer-gapCSS custom property--kui-space-2Footer gap
--kui-calendar-value-font-sizeCSS custom property--kui-text-xs-sizeValue font size
--kui-calendar-picker-grid-gapCSS custom property--kui-space-2Picker grid gap
--kui-calendar-picker-cell-padding-blockCSS custom property--kui-space-3Picker cell padding, block
--kui-calendar-picker-cell-padding-inlineCSS custom property--kui-space-2Picker cell padding, inline
--kui-calendar-picker-cell-radiusCSS custom property--kui-radius-smPicker cell corner radius
--kui-calendar-picker-cell-font-sizeCSS custom property--kui-text-sm-sizePicker cell font size
--kui-calendar-padding-smCSS custom property--kui-space-3Padding, sm
--kui-calendar-day-font-size-smCSS custom property--kui-text-xs-sizeDay font size, sm
--kui-calendar-weekday-font-size-smCSS custom property--kui-text-2xs-sizeWeekday font size, sm
--kui-calendar-width-smCSS custom property252pxWidth, sm

Messages

Every text the component owns (accessible names, visible words, announcements) is a typed message with an English default. Override it for the application with provideKikitaUi({ messages }), or for a subtree with provideKuiMessages.

NameTypeDefaultDescription
labelstring — Accessible name of the day grid. Default Calendar.
todaystring — Text of the footer shortcut to the current day. Default Today.
previousMonthstring — Previous button of the day view. Default Previous month.
nextMonthstring — Next button of the day view. Default Next month.
previousYearstring — Previous button of the month view. Default Previous year.
nextYearstring — Next button of the month view. Default Next year.
previousDecadestring — Previous button of the year view. Default Previous decade.
nextDecadestring — Next button of the year view. Default Next decade.

API

Inputs, models, projection slots, provider defaults, messages and locale helpers verified against @kikita-labs/ui v2.0.0 public typings.

NameTypeDefaultDescription
[(value)]Date | nullnullSelected date. For a start and end pair use kui-calendar-range, whose value is a KuiDateRange | null. Next to input[kuiDatePicker] in the same field the directive wires it for you.
messagesPartial<KuiCalendarMessages> | undefinedundefinedPer-instance text overrides (label, today, previousMonth, nextMonth, previousYear, nextYear, previousDecade, nextDecade). They win over scoped and root messages.
[(viewDate)]Datecurrent monthFirst-of-month date that controls the visible month.
size'md' | 'sm''md'Calendar density. Use sm when embedding in tighter sidebars or panels.
flatbooleanfalseRemoves the calendar frame for dropdown or popover panel composition.
showWeekendbooleantrueMutes the weekend days of the locale (Saturday and Sunday in en-US) when enabled.
showFooterbooleanfalseShows the built-in value summary and Today shortcut.
[(minDate)] / [(maxDate)]Date | undefinedundefinedInclusive lower and upper bounds for selectable days. Models, so a paired input[kuiDatePicker] can wire them from its own bounds.
disabledDatesDate[] | ((date: Date) => boolean) | undefinedundefinedIndividual disabled dates or a predicate evaluated for each rendered date.
localestring | undefinedKUI_LOCALEBCP 47 locale override for month names, weekday names, the heading, week start and weekend. It wins over the locale of the nearest KuiI18n level.
showPrevNav / showNextNavbooleantrueHide one header navigation control for linked multi-calendar layouts.
[kuiCalendarHeader] / [kuiCalendarFooter]projected content-Replace the default header or footer with consumer-owned content.
provideKuiLocale(locale)Provider[]-Sets the locale of a subtree (a tag, a Signal or a function). Use provideKikitaUi({ locale }) for the whole application.
--kui-calendar-widthCSS custom property296pxOverrides the fixed calendar width while keeping the day grid predictable.
KuiCalendarOptions / KuiCalendarViewOptionsinterfaces-Shape of defaults.calendar (size, flat, showWeekend, showFooter, showPrevNav, showNextNav, previousIcon, nextIcon), shared with kui-calendar-range.
KuiCalendarMessagesinterface-Typed messages of the calendar and the calendar range, with English defaults.
kui-pickedDOM event-Bubbling event the calendar dispatches after a date pick, so an enclosing kui-dropdown can close.

Accessibility

Calendar owns grid semantics and roving focus; consumers provide context around the picker.

  • The day grid is a complete ARIA grid: role="grid" holds the weekday header row (columnheader cells carry the full weekday name as abbr) and six week rows of seven gridcells, each wrapping one day button.
  • aria-selected sits on the selected gridcell, not on the button; today exposes aria-current="date" and disabled dates aria-disabled.
  • One day is in the tab order at a time: the selected date when it is in the displayed month, otherwise today when visible, otherwise the first day of the month.
  • Keyboard: ArrowLeft and ArrowRight move a day, ArrowUp and ArrowDown a week, Home and End the start and end of the week, PageUp and PageDown a month (with Shift a year), and Enter or Space selects. Focus follows into the next month.
  • Month and year changes are announced through an aria-live="polite" region.
  • Provide nearby text or a surrounding field label when the calendar appears in a larger form.
  • Assistive-technology review is still pending for the newest date primitives.

Migrating to 2.0

Consumer-visible changes of @kikita-labs/ui 2.0 for the calendar.

  • The class is KuiCalendar (it was KuiCalendarComponent); ng update @kikita-labs/ui renames the import.
  • kui-calendar is single-date only: the mode input and the Date | KuiDateRange | null value union are gone. Range selection moved to kui-calendar-range.
  • kuiProvideLocale is provideKuiLocale and returns an array of providers; the locale is checked against the runtime's Intl and falls back to en-US.
  • The grid markup is a full ARIA grid. CSS that targets .kui-calendar-grid > .kui-calendar-day must target .kui-calendar-day or the new week and cell wrappers; tests that look up a day button by its bare number must use the full date as its name.
sprint.html
<!-- 1.x -->
<kui-calendar mode="range" [(value)]="sprint" />

<!-- 2.0: a separate component, value is KuiDateRange | null -->
<kui-calendar-range [(value)]="sprint" />