Calendar Range
Inline month grid for selecting a start and end date.
Calendar Range is a standalone component. Its value is a KuiDateRange.
import { KuiCalendarRange, type KuiDateRange } from '@kikita-labs/ui';Bind value to a signal of KuiDateRange | null. The first click sets the start, hovering before the second click previews the range, and the second click commits it. The first click after a committed range starts a new one.
SunMonTueWedThuFriSat
SunMonTueWedThuFriSat
<div class="calendar-range-example">
<kui-calendar-range [(value)]="range" [(viewDate)]="viewDate" showFooter />
<kui-calendar-range size="sm" flat [(value)]="range" [(viewDate)]="viewDate" />
</div>viewDate defaults to the current month; the documented fallback to the month of value.start applies only when the value exists at construction, so bind [(viewDate)] to open the grid at the month of a template-bound range. end is null while the range is still open, so check it before using the value as a closed range. The header navigation and the Today button are ghost kuiButtons and the rule above the footer is hr[kuiSeparator]. Calendar Range reuses the Calendar stylesheet and class names, so it shares the Calendar theming tokens listed below.
minDate and maxDate are inclusive bounds. disabledDates takes dates or a predicate. showWeekend mutes the weekend of the locale.
SunMonTueWedThuFriSat
SunMonTueWedThuFriSat
<div class="calendar-range-example">
<kui-calendar-range
[(value)]="range"
[(viewDate)]="viewDate"
[minDate]="minDate"
[maxDate]="maxDate"
[disabledDates]="holidays"
/>
<kui-calendar-range
[(value)]="range"
[(viewDate)]="viewDate"
[disabledDates]="isWeekend"
[showWeekend]="false"
/>
</div>viewDate is a two-way model, so two ranges a month apart can be built from showPrevNav and showNextNav. A built-in range popover is not available; this layout is for custom compositions.
SunMonTueWedThuFriSat
SunMonTueWedThuFriSat
<div class="calendar-range-example">
<kui-calendar-range [(value)]="range" [(viewDate)]="leftView" [showNextNav]="false" />
<kui-calendar-range
[(value)]="range"
[viewDate]="rightView()"
(viewDateChange)="showFromRight($event)"
[showPrevNav]="false"
/>
</div>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. locale and messages override them for one instance.
日月火水木金土
MoDiMiDoFrSaSo
<div class="calendar-range-example">
<kui-calendar-range locale="ja-JP" size="sm" [(value)]="range" [(viewDate)]="viewDate" />
<kui-calendar-range
locale="de-DE"
size="sm"
showFooter
[messages]="messages"
[(value)]="range"
[(viewDate)]="viewDate"
/>
</div>Project an element with kuiCalendarHeader or kuiCalendarFooter to replace the matching default block completely.
SunMonTueWedThuFriSat
<kui-calendar-range [(value)]="range" [(viewDate)]="viewDate">
<div kuiCalendarFooter class="calendar-range-footer">
<button kuiButton shape="ghost" size="sm" type="button" (click)="clear()">Clear</button>
</div>
</kui-calendar-range>Set defaults.calendarRange once for the application or for a subtree. Each option resolves as local input > defaults.calendarRange.<option> > built-in default.
import { provideKikitaUi } from '@kikita-labs/ui';
export const appConfig: ApplicationConfig = {
providers: [
provideKikitaUi({
defaults: {
calendarRange: {
/* options below */
},
},
}),
],
};| Name | Type | Default | Description |
|---|---|---|---|
| size | 'md' | 'sm' | — | Calendar size. Takes precedence over the global defaults.size. |
| flat | boolean | — | Strips the calendar's own background, border and padding. |
| showWeekend | boolean | — | Shows Saturday and Sunday in a muted colour. |
| showFooter | boolean | — | Shows the footer with the current value and the "Today" shortcut. |
| showPrevNav | boolean | — | Shows the "previous" navigation control in the header. |
| showNextNav | boolean | — | Shows the "next" navigation control in the header. |
| previousIcon | KuiIconGlyph | — | Icon of the previous control. Takes precedence over defaults.icons.previous. See Structural Icons. |
| nextIcon | KuiIconGlyph | — | Icon of the next control. Takes precedence over defaults.icons.next. See Structural Icons. |
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.
| Name | Type | Default | Description |
|---|---|---|---|
| --kui-calendar-bg | CSS custom property | --kui-color-surface | Background |
| --kui-calendar-border | CSS custom property | --kui-color-border | Border color |
| --kui-calendar-color | CSS custom property | --kui-color-text | Color |
| --kui-calendar-title-color | CSS custom property | --kui-color-text | Title color |
| --kui-calendar-day-color | CSS custom property | --kui-color-text | Day color |
| --kui-calendar-day-focus-ring-color | CSS custom property | --kui-color-focus | Day focus ring color |
| --kui-calendar-day-color-muted | CSS custom property | --kui-color-text-secondary | Day color, muted |
| --kui-calendar-day-color-weekend | CSS custom property | --kui-color-text-secondary | Day color, weekend |
| --kui-calendar-day-bg-selected | CSS custom property | --kui-color-primary-fill | Day background, selected |
| --kui-calendar-day-color-selected | CSS custom property | --kui-color-primary-on-fill | Day color, selected |
| --kui-calendar-day-color-range-middle | CSS custom property | --kui-color-primary-soft-text | Day color, range middle |
| --kui-calendar-day-bg-range-start | CSS custom property | --kui-color-primary-fill | Day background, range start |
| --kui-calendar-day-color-range-start | CSS custom property | --kui-color-primary-on-fill | Day color, range start |
| --kui-calendar-day-bg-range-end | CSS custom property | --kui-color-primary-fill | Day background, range end |
| --kui-calendar-day-color-range-end | CSS custom property | --kui-color-primary-on-fill | Day color, range end |
| --kui-calendar-day-bg-range-edge-hover | CSS custom property | --kui-color-primary-fill-hover | Day background, range edge hover |
| --kui-calendar-day-bg-range-middle-hover | CSS custom property | ? | Day background, range middle hover |
| --kui-calendar-day-bg-selected-hover | CSS custom property | --kui-color-primary-fill-hover | Day background, selected hover |
| --kui-calendar-value-color | CSS custom property | --kui-color-text-secondary | Value color |
| --kui-calendar-picker-cell-color | CSS custom property | --kui-color-text | Picker cell color |
| --kui-calendar-picker-cell-focus-ring-color | CSS custom property | --kui-color-focus | Picker cell focus ring color |
| --kui-calendar-picker-cell-bg-active | CSS custom property | --kui-color-primary-fill | Picker cell background, active |
| --kui-calendar-picker-cell-color-active | CSS custom property | --kui-color-primary-on-fill | Picker cell color, active |
| --kui-calendar-picker-cell-color-muted | CSS custom property | --kui-color-text-secondary | Picker cell color, muted |
| Name | Type | Default | Description |
|---|---|---|---|
| --kui-calendar-radius | CSS custom property | --kui-radius-lg | Corner radius |
| --kui-calendar-padding | CSS custom property | --kui-space-4 | Padding |
| --kui-calendar-title-font-size | CSS custom property | --kui-text-sm-size | Title font size |
| --kui-calendar-title-padding-inline | CSS custom property | --kui-space-2 | Title padding, inline |
| --kui-calendar-nav-spacer-size | CSS custom property | --kui-control-height-xs | Nav spacer size |
| --kui-calendar-weekday-font-size | CSS custom property | --kui-text-xs-size | Weekday font size |
| --kui-calendar-weekday-padding-bottom | CSS custom property | --kui-space-2 | Weekday padding, bottom |
| --kui-calendar-day-font-size | CSS custom property | --kui-text-sm-size | Day font size |
| --kui-calendar-footer-gap | CSS custom property | --kui-space-2 | Footer gap |
| --kui-calendar-value-font-size | CSS custom property | --kui-text-xs-size | Value font size |
| --kui-calendar-picker-grid-gap | CSS custom property | --kui-space-2 | Picker grid gap |
| --kui-calendar-picker-cell-padding-block | CSS custom property | --kui-space-3 | Picker cell padding, block |
| --kui-calendar-picker-cell-padding-inline | CSS custom property | --kui-space-2 | Picker cell padding, inline |
| --kui-calendar-picker-cell-radius | CSS custom property | --kui-radius-sm | Picker cell corner radius |
| --kui-calendar-picker-cell-font-size | CSS custom property | --kui-text-sm-size | Picker cell font size |
| --kui-calendar-padding-sm | CSS custom property | --kui-space-3 | Padding, sm |
| --kui-calendar-day-font-size-sm | CSS custom property | --kui-text-xs-size | Day font size, sm |
| --kui-calendar-weekday-font-size-sm | CSS custom property | --kui-text-2xs-size | Weekday font size, sm |
| --kui-calendar-width-sm | CSS custom property | 252px | Width, sm |
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.
| Name | Type | Default | Description |
|---|---|---|---|
| label | string | — | Accessible name of the day grid. Default Calendar. |
| today | string | — | Text of the footer shortcut to the current day. Default Today. |
| previousMonth | string | — | Previous button of the day view. Default Previous month. |
| nextMonth | string | — | Next button of the day view. Default Next month. |
| previousYear | string | — | Previous button of the month view. Default Previous year. |
| nextYear | string | — | Next button of the month view. Default Next year. |
| previousDecade | string | — | Previous button of the year view. Default Previous decade. |
| nextDecade | string | — | Next button of the year view. Default Next decade. |
Inputs verified against @kikita-labs/ui v2.0.0 public typings.
| Name | Type | Default | Description |
|---|---|---|---|
| [(value)] | KuiDateRange | null | null | Selected range, { start: Date; end: Date | null }. end is null while only the start has been picked; the first click after a committed range starts a new one. |
| [(viewDate)] | Date | current month | First-of-month date that controls the visible month. Left unbound it defaults to today, or to the month of the bound value.start at construction. |
| size | 'md' | 'sm' | undefined | undefined | Calendar density. sm drops the border and padding for sidebars. Falls back to defaults.calendarRange.size, then the global defaults.size, then md. |
| flat | boolean | undefined | undefined | Strips the calendar background, border and padding, for dropdown or popover panels. Falls back to defaults.calendarRange.flat, then false. |
| showWeekend | boolean | undefined | undefined | Mutes the weekend days of the locale. Falls back to defaults.calendarRange.showWeekend, then true. |
| showFooter | boolean | undefined | undefined | Shows the built-in footer with the current value and the Today shortcut. Falls back to defaults.calendarRange.showFooter, then false. |
| showPrevNav / showNextNav | boolean | undefined | undefined | Hide the previous or next header navigation control, for two linked calendars a month apart. Fall back to defaults.calendarRange, then true. |
| minDate / maxDate | Date | undefined | undefined | Inclusive lower and upper bounds. Dates outside them are disabled. |
| disabledDates | Date[] | ((date: Date) => boolean) | undefined | undefined | Individual disabled dates or a predicate evaluated for each rendered date. |
| locale | string | undefined | undefined | BCP 47 locale for month and weekday names, heading order, week start and weekend. It overrides the locale of the nearest KuiI18n level for this instance. |
| messages | Partial<KuiCalendarMessages> | undefined | undefined | Per-instance text overrides, the same group as the calendar. They win over scoped and root messages. |
| [kuiCalendarHeader] / [kuiCalendarFooter] | projected content | - | Replace the default header or footer entirely; the built-in block (and the showFooter toggle) renders only when nothing is projected. |
| --kui-calendar-width | CSS custom property | 296px | Overrides the fixed calendar width, as for kui-calendar. |
| KuiDateRange | interface | - | The value shape: { start: Date; end: Date | null }. |
| KuiCalendarOptions / KuiCalendarViewOptions | interfaces | - | Shape of defaults.calendarRange (size, flat, showWeekend, showFooter, showPrevNav, showNextNav, previousIcon, nextIcon), shared with kui-calendar. |
Calendar Range has the same grid semantics and roving focus as Calendar.
- The day grid is a complete ARIA grid:
role="grid", a weekday header row ofcolumnheadercells and six weekrows of sevengridcells, each wrapping one day button. aria-selectedsits on the gridcells of the range endpoints and any single committed day; today exposesaria-current="date"and disabled datesaria-disabled.- One day cell is in the tab order at a time; the arrow keys,
Home,End,PageUpandPageDownmove focus without leaving the grid. - Keyboard:
ArrowLeftandArrowRightmove a day,ArrowUpandArrowDowna week,HomeandEndthe start and end of the week,PageUpandPageDowna month (withShifta year), andEnterorSpaceselects the focused date. - Month and year changes are announced through an
aria-live="polite"region.
Documented limits of the installed package.
- There is no built-in popover wrapper (a range equivalent of
input[kuiDatePicker]); the component is inline-only. - Selecting more than one start and end pair is not implemented.