GUILD OF GLEKS UIv21.19.0

gog-calendar

Calendar

The month grid behind Datepicker, exported and usable on its own for an always-visible calendar. Native Date throughout — no date library and no adapter abstraction, so the package keeps its zero runtime dependencies.

It is a date grid, not an event calendar. It picks a day, a range or a time; it does not lay out appointments across a week or a month the way Google Calendar does. For that, use a scheduler built for it, such as FullCalendar.

Overview

Import the component and drop it into a template.

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

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

Import it from @guildofgleks/ui/datepicker, together with gog-datepicker. The root package has not exported it since 21.14.0 — in 21.13.0 it still did, deprecated — and that is what lets a calendar used only behind a lazy route keep its own code out of your app's initial bundle. What it imports from the root does not move: the icons it draws belong to the root package, and load wherever your first page already loads it. Measured on a fresh app with the table, datepicker, calendar and dialog behind one lazy route: the initial bundle went from 101.2 kB to 88.2 kB, and 27 kB of those components' root dependencies stayed in it.

Basic usage — [(value)] holds a Date. The grid always renders six weeks, so its height never changes as you page through months: a calendar that grows and shrinks by a row shifts whatever sits under it, and inside a dropdown panel moves the panel itself.

November 2026
Sun Mon Tue Wed Thu Fri Sat

value: 19/11/2026

<gog-calendar [(value)]="day" />
<p>value: {{ show(day()) }}</p>

Examples

Sizes

Five steps of day cell and type. A weekday column is as wide as a day, so at xsm and sm — 24 and 28px — the weekday row draws the locale's narrow form (S M T …) 21.15.1, where a three-letter name would outgrow its column.

xsm

November 2026
S M T W T F S

sm

November 2026
S M T W T F S

md

November 2026
Sun Mon Tue Wed Thu Fri Sat

lg

November 2026
Sun Mon Tue Wed Thu Fri Sat

slg

November 2026
Sun Mon Tue Wed Thu Fri Sat
@for (size of sizes; track size) {
  <div>
    <p>{{ size }}</p>
    <gog-calendar [size]="size" />
  </div>
}

Range, and the two outputs

In range mode the value is a { start, end } pair, and two months side by side is what makes picking one practical. The two outputs are not the same event: valueChange fires for every change, including the first press of a range; gogDateSelect fires only when the selection is complete — a day in single mode, both ends in range mode. That is the one gog-datepicker closes its panel on.

single

November 2026
Sun Mon Tue Wed Thu Fri Sat

range, two months

November 2026December 2026
Sun Mon Tue Wed Thu Fri Sat
Sun Mon Tue Wed Thu Fri Sat

single: null · range: null · 0 valueChange · 0 gogDateSelect

<div>
  <p>single</p>
  <gog-calendar
    [(value)]="day"
    (valueChange)="changes.update((n) => n + 1)"
    (gogDateSelect)="selects.update((n) => n + 1)"
  />
</div>

<!-- In range mode valueChange fires on both presses; gogDateSelect only on the second. -->
<div>
  <p>range, two months</p>
  <gog-calendar
    selectionMode="range"
    [numberOfMonths]="2"
    [(value)]="range"
    (valueChange)="changes.update((n) => n + 1)"
    (gogDateSelect)="selects.update((n) => n + 1)"
  />
</div>

<p>
  single: {{ show(day()) }} · range: {{ show(range()) }} · {{ changes() }} valueChange ·
  {{ selects() }} gogDateSelect
</p>

Bounds and disabled dates

min and max cover the bounded case — days outside them are disabled, not hidden. 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: this week only

November 2026
Sun Mon Tue Wed Thu Fri Sat

disabledDates: weekends

November 2026
Sun Mon Tue Wed Thu Fri Sat

workday: null

<!-- min and max: days outside them are disabled, not hidden. -->
<div>
  <p>min and max: this week only</p>
  <gog-calendar [min]="weekStart" [max]="weekEnd" />
</div>

<!-- disabledDates is a predicate, so "every weekend" needs no list of dates. -->
<div>
  <p>disabledDates: weekends</p>
  <gog-calendar [disabledDates]="weekends" [(value)]="workday" />
</div>

<p>workday: {{ show(workday()) }}</p>

Time

showTime adds a clock under the grid; hourFormat, minuteStep and showSeconds configure it. The value stays a single Date, carrying the time.

24-hour, 15-minute steps

November 2026
Sun Mon Tue Wed Thu Fri Sat

12-hour, with seconds

November 2026
Sun Mon Tue Wed Thu Fri Sat

meeting: null · alarm: null

<div>
  <p>24-hour, 15-minute steps</p>
  <gog-calendar showTime hourFormat="24" [minuteStep]="15" [(value)]="meeting" />
</div>
<div>
  <p>12-hour, with seconds</p>
  <gog-calendar showTime hourFormat="12" showSeconds [(value)]="alarm" />
</div>
<p>meeting: {{ show(meeting()) }} · alarm: {{ show(alarm()) }}</p>

The two footer buttons

Deliberately two controls, not one. Todayselects today's date; This month only moves the view back and leaves the selection alone. One button doing both read as "take me back" to one person and "set it to today" to another, and no wording fixed that. Where min or disabledDates rule today out, Today is disabled rather than silently doing nothing.

default: Today only

November 2026
S M T W T F S

showThisMonthButton

November 2026
S M T W T F S

min next year: Today disabled

January 2027
S M T W T F S

showTodayButton false: no footer

November 2026
S M T W T F S
<div>
  <p>default: Today only</p>
  <gog-calendar size="sm" />
</div>
<div>
  <p>showThisMonthButton</p>
  <gog-calendar size="sm" showThisMonthButton />
</div>
<!-- Where min puts today out of range, Today is disabled rather than doing nothing. -->
<div>
  <p>min next year: Today disabled</p>
  <gog-calendar size="sm" [min]="nextYear" [defaultMonth]="nextYear" showThisMonthButton />
</div>
<div>
  <p>showTodayButton false: no footer</p>
  <gog-calendar size="sm" [showTodayButton]="false" />
</div>

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.

de-DE, weeks start on Monday

November 2026
Mo Di Mi Do Fr Sa So

ja-JP

11月 2026
日 月 火 水 木 金 土
<div>
  <p>de-DE, weeks start on Monday</p>
  <gog-calendar locale="de-DE" [firstDayOfWeek]="1" />
</div>
<div>
  <p>ja-JP</p>
  <gog-calendar locale="ja-JP" />
</div>

The nine labels

Every string the calendar renders is an input — the two footer buttons, the four navigation arrows and the three time fields — and each falls back to GOG_CONFIG.labels, then to English. Inspect the arrows: their accessible names are German too. gog-datepicker takes the same nine 21.15.0 and hands them to its calendar.

November 2026
Mo Di Mi Do Fr Sa So
<!-- Each of the nine strings is an input; unset, it falls back to GOG_CONFIG.labels. -->
<gog-calendar
  locale="de-DE"
  showTime
  showThisMonthButton
  todayLabel="Heute"
  thisMonthLabel="Dieser Monat"
  previousMonthLabel="Voriger Monat"
  nextMonthLabel="Nächster Monat"
  previousYearLabel="Voriges Jahr"
  nextYearLabel="Nächstes Jahr"
  hoursLabel="Stunden"
  minutesLabel="Minuten"
  secondsLabel="Sekunden"
/>

Width in a block container

The grid caps itself at its own width: --gog-calendar-max-width is max-content by default and follows numberOfMonths, showTime and the size steps on its own. Each calendar here is as wide as the card, so without the cap the header would spread across while the days huddled at the start. Set it to 100% for a calendar that fills its container.

default

November 2026
Sun Mon Tue Wed Thu Fri Sat

two months and a time — the same cap, no numbers involved

November 2026December 2026
Sun Mon Tue Wed Thu Fri Sat
Sun Mon Tue Wed Thu Fri Sat

--gog-calendar-max-width: 100%

November 2026
Sun Mon Tue Wed Thu Fri Sat
<!-- Each calendar is the only child of a full-width block: it caps itself at its own grid. -->
<p>default</p>
<gog-calendar />

<p>two months and a time — the same cap, no numbers involved</p>
<gog-calendar [numberOfMonths]="2" showTime />

<p>--gog-calendar-max-width: 100%</p>
<gog-calendar style="--gog-calendar-max-width: 100%" />

App-wide defaults — GOG_CONFIG

A standalone calendar resolves locale and firstDayOfWeek from GOG_CONFIG.datepicker itself, and its labels from GOG_CONFIG.labels — no datepicker involved. An instance's own input still wins. In an app the provider goes in app.config.ts — see Global Configuration.

locale and first day from the config

novembre 2026
lun. mar. mer. jeu. ven. sam. dim.

locale="en-US" — the instance wins

November 2026
Mon Tue Wed Thu Fri Sat Sun
<div>
  <p>locale and first day from the config</p>
  <gog-calendar />
</div>
<div>
  <p>locale="en-US" — the instance wins</p>
  <gog-calendar locale="en-US" />
</div>

Accessibility

The days follow the ARIA grid pattern, and all 42 cells share one tab stop, so tabbing past the calendar does not mean 42 presses. The navigation arrows are buttons named by their labels.

  • Keyboard — the arrows move by a day and a week, Home/End to the ends of the week, PageUp/PageDown by a month and with Shift by a year, Enter or Space picks.
  • Focus follows the highlight21.15.0 — the arrows move the focus ring and not only the roving tabindex, so a screen reader announces each day as it is reached.
  • Weekday columns21.15.1 — each column header is named by the whole day (aria-label="Monday") at every size, so the narrow letters of the small sizes, where two columns read S, are never what is heard.
  • Disabled days — outside min/max or matched by disabledDates, they stay in the grid and cannot be picked.

API Reference

Inputs

NameTypeDefaultDescription
valueDate | GogDateRange | nullnullThe 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 / maxDate | nullnullSelectable bounds. Days outside them are disabled, not hidden.
disabledDates((date: Date) => boolean) | nullnullExtra exclusions, as a predicate rather than a list — an array cannot express "weekends" or "public holidays" without materialising every date in range first.
localestring | 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.
firstDayOfWeeknumber | undefinedthe locale's own0 = Sunday … 6 = Saturday. Unset, falls back to GOG_CONFIG.datepicker.firstDayOfWeek, then to the locale.
defaultMonthDate | nullnullWhich month to open on when there is no selection yet.
numberOfMonthsnumber1How many months to show side by side. Two is what makes a range usable.
showTimebooleanfalseAdds a clock under the grid.
hourFormat / minuteStep / showSeconds'12' | '24' / number / boolean'24' / 1 / falseHow that clock is configured.
showTodayButtonbooleantrueThe "Today" button, which SELECTS today. Disabled when min/max or disabledDates rule today out, rather than silently doing nothing.
showThisMonthButtonbooleanfalseThe "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 / thisMonthLabelstring | undefined'Today' / 'This month'Wording for the two footer actions. Also settable app-wide via GOG_CONFIG.labels.
previousMonthLabel / nextMonthLabel / previousYearLabel / nextYearLabelstring | 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 / secondsLabelstring | undefined'Hours' / 'Minutes' / 'Seconds'Accessible names for the time section's three spinners (with showTime). Also settable app-wide via GOG_CONFIG.labels.

Outputs

NamePayloadDescription
gogDateSelectDate | GogDateRange | nullEmitted 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.
valueChangeDate | GogDateRange | nullThe value model’s change event, for [(value)].

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.datepicker.locale
  • GOG_CONFIG.datepicker.firstDayOfWeek
  • GOG_CONFIG.labels.today
  • GOG_CONFIG.labels.thisMonth
  • GOG_CONFIG.labels.previousMonth
  • GOG_CONFIG.labels.nextMonth
  • GOG_CONFIG.labels.previousYear
  • GOG_CONFIG.labels.nextYear
  • GOG_CONFIG.labels.hours — time selection
  • GOG_CONFIG.labels.minutes — time selection
  • GOG_CONFIG.labels.seconds — time selection

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.

TokenDescription
--gog-calendar-max-widthHow 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-gapGrid 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-radiusDay cell size and shape.
--gog-calendar-day-rest-bg / -day-hover-bg / -day-outside-colorDay cell states, including days spilling in from the neighbouring month.
--gog-calendar-selected-bg / -selected-color / -selected-font-weightThe selected day.
--gog-calendar-range-bg / -range-colorDays between the two ends of a range selection.
--gog-calendar-today-border-color / -today-font-weightThe ring marking today.
--gog-calendar-nav-bg / -nav-hover-bg / -nav-size / -nav-icon-sizePrevious/next month and year buttons.
--gog-calendar-weekday-color / -weekday-font-size / -weekday-text-transformWeekday header row.
--gog-calendar-time-input-bg / -time-input-width / -time-gapThe clock section shown under the grid when showTime is on.