Sizes
xsm
| S | M | T | W | T | F | S |
|---|---|---|---|---|---|---|
sm
| S | M | T | W | T | F | S |
|---|---|---|---|---|---|---|
md
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
lg
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
slg
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
gog-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.
Import the component and drop it into a template.
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.
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
value: 19/11/2026
<gog-calendar [(value)]="day" />
<p>value: {{ show(day()) }}</p> 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 …)
xsm
| S | M | T | W | T | F | S |
|---|---|---|---|---|---|---|
sm
| S | M | T | W | T | F | S |
|---|---|---|---|---|---|---|
md
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
lg
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
slg
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
@for (size of sizes; track size) {
<div>
<p>{{ size }}</p>
<gog-calendar [size]="size" />
</div>
} 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
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
range, two months
| 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>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
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
disabledDates: weekends
| 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>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
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
12-hour, with seconds
| 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> 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
| S | M | T | W | T | F | S |
|---|---|---|---|---|---|---|
showThisMonthButton
| S | M | T | W | T | F | S |
|---|---|---|---|---|---|---|
min next year: Today disabled
| S | M | T | W | T | F | S |
|---|---|---|---|---|---|---|
showTodayButton false: no footer
| 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> 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
| Mo | Di | Mi | Do | Fr | Sa | So |
|---|---|---|---|---|---|---|
ja-JP
| 日 | 月 | 火 | 水 | 木 | 金 | 土 |
|---|---|---|---|---|---|---|
<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> 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
| 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"
/> 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
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
two months and a time — the same cap, no numbers involved
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
--gog-calendar-max-width: 100%
| 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%" />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
| lun. | mar. | mer. | jeu. | ven. | sam. | dim. |
|---|---|---|---|---|---|---|
locale="en-US" — the instance wins
| 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>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.
tabindex, so a screen reader announces each day as it is reached. aria-label="Monday") at every size, so the narrow letters of the small sizes, where two columns read S, are never what is heard. min/max or matched by disabledDates, they stay in the grid and cannot be picked. | 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 | string | undefined | 'Hours' / 'Minutes' / 'Seconds' | Accessible names for the time section's three spinners (with showTime). Also settable app-wide via GOG_CONFIG.labels. |
| 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)]. |
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.localeGOG_CONFIG.datepicker.firstDayOfWeekGOG_CONFIG.labels.todayGOG_CONFIG.labels.thisMonthGOG_CONFIG.labels.previousMonthGOG_CONFIG.labels.nextMonthGOG_CONFIG.labels.previousYearGOG_CONFIG.labels.nextYearGOG_CONFIG.labels.hours — time selectionGOG_CONFIG.labels.minutes — time selectionGOG_CONFIG.labels.seconds — time selectionEvery 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. |