Overview

Import the component and drop it into a template.

import { CalendarComponent } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [CalendarComponent],
})

Basic usage:

value = Wed Aug 19 2026

<gog-calendar [(value)]="day" />

Six weeks, always

The grid always renders six weeks, so its height never changes as you page through months. A calendar that grows and shrinks by one row shifts whatever sits under it — and inside a dropdown panel, moves the panel itself.

Examples

Range, two months

In range mode the value is a { start, end } pair. Two months side by side is what makes picking one practical.

value = null

<gog-calendar selectionMode="range" [numberOfMonths]="2" [(value)]="range" />

Disabled dates

disabledDates is a predicate, not an array — "weekends" and "public holidays" have no finite list a consumer could hand over without materialising every date in range first. min and max cover the bounded case.

value = null

<gog-calendar [disabledDates]="weekends" [(value)]="workday" />

Time, and the two footer buttons

showTime adds a clock under the grid. The footer carries two separate actions, never one: "Today" selects today, and "This month" only moves the view back. A single button doing both is ambiguous — after paging away, the same label reads as "take me back" to one person and "set it to today" to another. "Today" is disabled when min/max or disabledDates rule today out, rather than silently doing nothing.

value = null

<gog-calendar
  [showTime]="true"
  hourFormat="24"
  [minuteStep]="15"
  [showThisMonthButton]="true"
  [(value)]="moment"
/>

Locale

Month and weekday names come from Intl, so any BCP-47 tag works with no data to ship. firstDayOfWeek overrides the locale's own choice. Both resolve the usual way — instance input, then GOG_CONFIG.datepicker, then the default 21.3.2 — so a standalone calendar honours an app-wide locale without being handed one.

Its navigation, shortcut and time labels (todayLabel, thisMonthLabel, previousMonthLabel, nextMonthLabel, previousYearLabel, nextYearLabel, hoursLabel, minutesLabel, secondsLabel) resolve through GOG_CONFIG.labels the same way — see Global Configuration.

<gog-calendar locale="de-DE" [firstDayOfWeek]="1" />
<gog-calendar locale="ja-JP" />

Accessibility

The grid follows the ARIA grid pattern: arrow keys move by day, PageUp/PageDown by month, Shift with those by year, and Home/End jump to the week's ends. All 42 cells share one tab stop, so tabbing past the calendar does not mean 42 presses.

API Reference

Inputs

Name	Type	Default	Description
`value`	`Date \| GogDateRange \| null`	`null`	The selection: a Date in single mode, a { start, end } pair in range mode. Two-way bindable with [(value)].
`selectionMode`	`'single' \| 'range'`	`'single'`	Whether the grid picks one day or a start/end pair.
`min / max`	`Date \| null`	`null`	Selectable bounds. Days outside them are disabled, not hidden.
`disabledDates`	`((date: Date) => boolean) \| null`	`null`	Extra exclusions, as a predicate rather than a list — an array cannot express "weekends" or "public holidays" without materialising every date in range first.
`locale`	`string \| undefined`	`'en-US'`	BCP-47 tag driving month and weekday names, through Intl. Unset, falls back to GOG_CONFIG.datepicker.locale — the calendar resolves it itself, with no datepicker involved.
`firstDayOfWeek`	`number \| undefined`	`the locale's own`	0 = Sunday … 6 = Saturday. Unset, falls back to GOG_CONFIG.datepicker.firstDayOfWeek, then to the locale.
`defaultMonth`	`Date \| null`	`null`	Which month to open on when there is no selection yet.
`numberOfMonths`	`number`	`1`	How many months to show side by side. Two is what makes a range usable.
`showTime`	`boolean`	`false`	Adds a clock under the grid.
`hourFormat / minuteStep / showSeconds`	`'12' \| '24' / number / boolean`	`'24' / 1 / false`	How that clock is configured.
`showTodayButton`	`boolean`	`true`	The "Today" button, which SELECTS today. Disabled when min/max or disabledDates rule today out, rather than silently doing nothing.
`showThisMonthButton`	`boolean`	`false`	The "This month" button, which only moves the VIEW back and leaves the selection alone.
`size`	`'xsm' \| 'sm' \| 'md' \| 'lg' \| 'slg'`	`'md'`	Day-cell and typography scale.
`todayLabel / thisMonthLabel`	`string \| undefined`	`'Today' / 'This month'`	Wording for the two footer actions. Also settable app-wide via GOG_CONFIG.labels.
`previousMonthLabel / nextMonthLabel / previousYearLabel / nextYearLabel`	`string \| undefined`	`'Previous month' / 'Next month' / 'Previous year' / 'Next year'`	Accessible names for the navigation buttons. Also settable app-wide via GOG_CONFIG.labels.
`hoursLabel / minutesLabel / secondsLabel`21.3.2	`string \| undefined`	`'Hours' / 'Minutes' / 'Seconds'`	Accessible names for the time section's three spinners (with showTime). Also settable app-wide via GOG_CONFIG.labels.

Outputs

Name	Payload	Description
`gogDateSelect`	`Date \| GogDateRange \| null`	Emitted when a selection is complete — a day in single mode, both ends of a range in range mode. Picking just the first end of a range does not emit.
`valueChange`	`Date \| GogDateRange \| null`	The value model’s change event, for [(value)].

Styling Tokens

Every CSS custom property the calendar paints with. These also theme the grid inside gog-datepicker's panel. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

Token	Description
`--gog-calendar-max-width`	How wide the calendar may get. Defaults to max-content, which caps it at its own month grid and follows the size steps, numberOfMonths and showTime on its own — set it to 100% for a calendar that fills its container instead. Also sizes gog-datepicker in inline mode, which renders this component.
`--gog-calendar-padding / -header-gap / -footer-gap / -months-gap`	Grid padding and the gaps between header, footer and side-by-side months.
`--gog-calendar-day-size (per size step: xsm/sm/md/lg/slg) / -day-radius`	Day cell size and shape.
`--gog-calendar-day-rest-bg / -day-hover-bg / -day-outside-color`	Day cell states, including days spilling in from the neighbouring month.
`--gog-calendar-selected-bg / -selected-color / -selected-font-weight`	The selected day.
`--gog-calendar-range-bg / -range-color`	Days between the two ends of a range selection.
`--gog-calendar-today-border-color / -today-font-weight`	The ring marking today.
`--gog-calendar-nav-bg / -nav-hover-bg / -nav-size / -nav-icon-size`	Previous/next month and year buttons.
`--gog-calendar-weekday-color / -weekday-font-size / -weekday-text-transform`	Weekday header row.
`--gog-calendar-time-input-bg / -time-input-width / -time-gap`	The clock section shown under the grid when showTime is on.

日	月	火	水	木	金	土

Sun	Mon	Tue	Wed	Thu	Fri	Sat

Sun	Mon	Tue	Wed	Thu	Fri	Sat

Sun	Mon	Tue	Wed	Thu	Fri	Sat

Sun	Mon	Tue	Wed	Thu	Fri	Sat