Sizes
Five steps, also settable app-wide through GOG_CONFIG.control.size.
@for (size of sizes; track size) {
<gog-datepicker [size]="size" [label]="size" [value]="today" />
}gog-datepicker
A date field with a calendar panel: a single date, a range, and an optional clock. Native Date, no date library and no adapter abstraction — the package keeps its zero runtime dependencies.
Import the component and drop it into a template.
import { DatepickerComponent } from '@guildofgleks/ui/datepicker';
@Component({
// ...
imports: [DatepickerComponent],
})
Import it from @guildofgleks/ui/datepicker, together with gog-calendar. 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 datepicker 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 — a birth date, so max is today. [(value)] holds a Date:
value: null<div>
<gog-datepicker label="Date of birth" [max]="today" [(value)]="birthday" />
<code>value: {{ show(birthday()) }}</code>
</div> Five steps, also settable app-wide through GOG_CONFIG.control.size.
@for (size of sizes; track size) {
<gog-datepicker [size]="size" [label]="size" [value]="today" />
} Empty, holding a value, disabled, and with an error. The calendar button is not optional — it is the one affordance that says this field is more than a text box, and it is what openCalendarLabel names.
<gog-datepicker label="Value unset" placeholder="dd.MM.yyyy" />
<gog-datepicker label="Value set" [value]="today" />
<gog-datepicker label="Disabled" [value]="today" disabled />
<gog-datepicker label="Error" errorMessage="Choose a date" />clearable is off by default and puts a second button beside the calendar one. Unlike gog-autocomplete it watches the value, not the text: a half-typed date that has not parsed yet leaves it hidden, because nothing committed is there to clear.
<gog-datepicker label="clearable unset" [value]="today" />
<gog-datepicker label="clearable" clearable [value]="today" />
<!-- Watches the value, not the text: a half-typed date leaves it hidden. -->
<gog-datepicker label="clearable, no value" placeholder="dd.MM.yyyy" clearable /> A field fills its container by default — the dashed box here. With [fullWidth]="false" it falls back to a text input's own width; there is no minWidth, since there is no selected label for it to collapse onto.
<gog-datepicker label="fullWidth (default)" [value]="today" />
<gog-datepicker label='[fullWidth]="false"' [fullWidth]="false" [value]="today" />ariaLabel names a field with no label, and the panel takes the same name. placeholder is empty by default, which is why stating the format in it is worth doing.
<!-- The panel takes the same name. State the format in the placeholder: it is empty by default. -->
<gog-datepicker ariaLabel="Date (no visible label)" placeholder="dd.MM.yyyy" />[(value)] holds a Date; valueChange fires on every change, a picked day, typed text that parses, and a clear.
value: null · 0 valueChange<div>
<gog-datepicker
label="Date"
clearable
[(value)]="date"
(valueChange)="changes.update((n) => n + 1)"
/>
<code>value: {{ show(date()) }} · {{ changes() }} valueChange</code>
</div>selectionMode="range" makes the value a { start, end } pair, and two months side by side is what makes picking one usable. The panel stays open between the two presses and hovering previews the second; only the second press completes the selection and closes it. The half-picked range is a valueChange of its own, because a form bound to the field has to see what the user currently means — gogDateSelect
value: null · 0 valueChange · 0 gogDateSelect<!-- The half-picked range is a valueChange of its own; gogDateSelect waits for both ends. -->
<div>
<gog-datepicker
label="Stay"
selectionMode="range"
[numberOfMonths]="2"
clearable
[(value)]="stay"
(valueChange)="changes.update((n) => n + 1)"
(gogDateSelect)="selects.update((n) => n + 1)"
/>
<code
>value: {{ show(stay()) }} · {{ changes() }} valueChange · {{ selects() }} gogDateSelect</code
>
</div>min and max bound the range; disabledDates takes a predicate, because an array cannot express "weekends" or "public holidays" without materialising every date first. A disabled day is a disabled button: announced, and neither the pointer nor Enter takes it. defaultMonth decides which month opens when nothing is selected.
<gog-datepicker label="From today on" [min]="today" />
<gog-datepicker label="This month only" [min]="monthStart" [max]="monthEnd" />
<!-- A predicate: "weekends" has no finite list of dates. -->
<gog-datepicker label="No weekends" [disabledDates]="noWeekends" />
<!-- defaultMonth: which month opens when nothing is selected yet. -->
<gog-datepicker label="Opens on next year" [defaultMonth]="nextYear" [min]="nextYear" />showTime adds a clock under the grid, and format gains HH:mm on its own. A field with a time does not close when a day is picked — the clock would be unreachable — so the panel waits for a press outside or Esc. If you set format yourself, include the time in it, or the field prints a time it cannot read back.
value: null<!-- With a time the panel stays open after a day is picked: the clock is below the grid. -->
<div>
<gog-datepicker label="24-hour" showTime [(value)]="meeting" />
<code>value: {{ show(meeting()) }}</code>
</div>
<gog-datepicker label="12-hour" showTime hourFormat="12" />
<gog-datepicker label="15-minute steps, seconds" showTime [minuteStep]="15" showSeconds />format is a token pattern — yyyy, MM, dd, HH, hh, mm, ss, a — used to print and to parse, so whatever the field shows can be typed back. A draft that does not parse leaves the value alone rather than clearing it, and blur snaps the text back. 31.02.2026 is rejected rather than becoming 3 March. A range field is read-only whatever allowTextInput says: there is no pattern for two dates and a dash.
value: null<!-- format is used to print and to parse: whatever the field shows can be typed back. -->
<div>
<gog-datepicker label="format unset (dd.MM.yyyy)" [(value)]="date" />
<code>value: {{ show(date()) }}</code>
</div>
<gog-datepicker label='format="yyyy-MM-dd"' format="yyyy-MM-dd" />
<gog-datepicker label="allowTextInput off" [allowTextInput]="false" [value]="today" />
<!-- A range field is read-only: there is no pattern for two dates and a dash. -->
<gog-datepicker label="Range (read-only text)" selectionMode="range" [numberOfMonths]="2" /> Month and weekday names come from Intl, so a locale is all a translated calendar needs. The first day of the week follows the locale unless firstDayOfWeek overrides it. The date format is deliberately not derived from the locale: it is the pattern in format.
<gog-datepicker label="en-US (default)" [value]="today" />
<gog-datepicker label="de-DE" locale="de-DE" [value]="today" />
<gog-datepicker label="ja-JP" locale="ja-JP" [value]="today" />
<!-- firstDayOfWeek overrides the locale: 0 is Sunday. -->
<gog-datepicker
label="en-GB, week from Sunday"
locale="en-GB"
[firstDayOfWeek]="0"
[value]="today"
/> The field's own openCalendarLabel and clearAriaLabel, plus the nine strings of the calendar inside it
<!-- The same nine strings as gog-calendar, handed to the calendar inside the field. -->
<gog-datepicker
label="Datum"
locale="de-DE"
showTime
showThisMonthButton
openCalendarLabel="Kalender öffnen"
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"
/>appendToBody The panel is a role="dialog" holding the calendar. It renders inline by default and is clipped by any scrolling or overflow: hidden ancestor; open both — only the appended one survives its box. It follows the field on scroll, and --gog-datepicker-panel-width is the knob if the panel needs a width.
<!-- Each box clips its content, as an overflow: hidden card or a scroller does. -->
<div style="overflow: hidden; padding: 12px; border: 1px dashed var(--gog-border-color)">
<gog-datepicker label="Inline panel (clipped)" dropdownDirection="down" />
</div>
<div style="overflow: hidden; padding: 12px; border: 1px dashed var(--gog-border-color)">
<gog-datepicker label="appendToBody (escapes)" dropdownDirection="down" appendToBody />
</div>inline drops the field and the panel and renders the calendar permanently — literally gog-calendar. The inputs that describe the field (label, clearable, floatLabel, appendToBody) have nothing to act on.
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
|---|---|---|---|---|---|---|
value: null
<!-- No field and no panel: literally gog-calendar. -->
<gog-datepicker inline [(value)]="date" />
<p>value: {{ show(date()) }}</p>'none' keeps the label above the field; 'in', 'on' and 'over' rest it inside until focus or a value moves it clear — each shown empty, then with a value. floatLabelShowPlaceholder shows the format once the label has floated.
@for (variant of variants; track variant) {
<gog-datepicker
[floatLabel]="variant"
[label]="'floatLabel: ' + variant"
placeholder="dd.MM.yyyy"
/>
<gog-datepicker [floatLabel]="variant" [label]="'floatLabel: ' + variant" [value]="today" />
}
<!-- The format shows under the floated label once it has somewhere to float to. -->
<gog-datepicker
floatLabel="over"
floatLabelShowPlaceholder
label="floatLabelShowPlaceholder"
placeholder="dd.MM.yyyy"
/> A ControlValueAccessor. With errorDisplay="auto" the error appears once the control is touched and invalid — closing the panel marks it touched, as blurring the field does. Open the panel and close it without choosing.
value: null · touched: false · disabled: false <div>
<!-- Closing the panel marks the control touched, as blurring the field does. -->
<gog-datepicker
label="Date (reactive form)"
placeholder="dd.MM.yyyy"
[formControl]="control"
errorMessage="Choose a date"
errorDisplay="auto"
clearable
/>
<div>
<gog-button variant="outline" size="sm" (gogClick)="control.markAsTouched()">
markAsTouched()
</gog-button>
<gog-button variant="outline" size="sm" (gogClick)="toggleDisabled()">
{{ control.disabled ? 'enable()' : 'disable()' }}
</gog-button>
</div>
<code>
value: {{ show(control.value) }} · touched: {{ control.touched }} · disabled:
{{ control.disabled }}
</code>
</div>GOG_CONFIG This is the component that earns the config most: an app states its locale, first day of week and date format once, and every field agrees. Open the first field — the week starts on Sunday though de-DE would choose Monday: firstDayOfWeek overrides the locale, one layer down. An instance's own input still wins. In an app the provider goes in app.config.ts — see Global Configuration.
<gog-datepicker label="Size, locale and format from the config" [value]="today" />
<gog-datepicker label='size="sm" — the instance wins' size="sm" [value]="today" /> The trigger is a text input that owns a dialog: aria-haspopup="dialog" rather than a combobox, because what opens is a grid of days and not a list of options. The grid follows the ARIA grid pattern — see Calendar.
label or ariaLabel; the calendar button is named by openCalendarLabel, the clear button by clearAriaLabel. errorMessage sets aria-invalid and links the message with aria-describedby. | 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 field picks one day or a start/end pair. |
format | string | null | GOG_CONFIG.datepicker.format ?? 'dd.MM.yyyy' (or '... HH:mm' when showTime is true) | A token pattern (yyyy, MM, dd, HH, hh, mm, ss, a) used for BOTH rendering and parsing, so what is written can always be read back. Left unset, it is derived from showTime automatically; an explicit value overrides that derivation, so widen it yourself if you set one and also turn showTime on. |
locale | string | GOG_CONFIG.datepicker.locale ?? 'en-US' | BCP-47 tag driving month and weekday names, through Intl. |
firstDayOfWeek | number | GOG_CONFIG.datepicker.firstDayOfWeek ?? from the locale | 0 = Sunday … 6 = Saturday. |
min / max | Date | null | null | Selectable bounds. |
disabledDates | ((date: Date) => boolean) | null | null | Extra exclusions as a predicate — an array cannot express "weekends". |
defaultMonth | Date | null | null | Which month the panel opens on when there is no selection yet. |
numberOfMonths | number | 1 | Months shown side by side. Two is what makes a range picker 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 / showThisMonthButton | boolean | true / false | Two separate footer actions: "Today" SELECTS today; "This month" only moves the view back. |
todayLabel / thisMonthLabel / openCalendarLabel / clearAriaLabel | string | 'Today' / 'This month' / 'Open calendar' / 'Clear date' | Wording for the footer actions and the two icon buttons. |
previousMonthLabel / nextMonthLabel / previousYearLabel / nextYearLabel / hoursLabel / minutesLabel / secondsLabel | string | undefined | GOG_CONFIG.labels.* | Accessible names for the panel calendar's navigation arrows and time inputs, handed to the calendar inside the field. Before 21.15.0 the field forwarded only todayLabel and thisMonthLabel, so these could be set only app-wide — two fields in different languages on one page could not be. |
allowTextInput | boolean | true | Whether the date can be typed as well as picked. Parsing uses the same pattern as rendering, so 31.02.2026 is rejected rather than silently becoming 3 March. |
inline | boolean | false | Renders the calendar always-visible, with no field. Literally gog-calendar on its own. |
clearable | boolean | GOG_CONFIG.control.clearable ?? false | A clear button, shown only once a date is set. |
label / ariaLabel / placeholder / inputId | string | '' | Field label, accessible name, placeholder, and an id for an external <label>. |
floatLabel / floatLabelShowPlaceholder | 'none' | 'in' | 'on' | 'over' / boolean | GOG_CONFIG.floatLabel.* ?? 'none' / false | Float-label variant and whether the placeholder reappears once it has floated. |
errorMessage / errorDisplay | string / 'manual' | 'auto' | '' / GOG_CONFIG.control.errorDisplay ?? 'manual' | Validation message, shown manually or derived from the bound form control. |
size / disabled / fullWidth | GogSize / boolean / boolean | GOG_CONFIG.control.size ?? 'md' / false / true | Density, disabled state, and how the field sizes itself. |
appendToBody / dropdownDirection / dropdownZIndex | boolean / GogDropdownDirection / number | null | GOG_CONFIG.dropdown.* ?? component defaults | Panel placement. appendToBody renders it into <body> so an overflow-clipped ancestor cannot cut it off. |
| Name | Payload | Description |
|---|---|---|
valueChange | Date | GogDateRange | null | Emitted when the value changes — including a half-picked range and typed text. Comes from the value model input. |
gogDateSelect | GogDatepickerValue | A complete selection made in the calendar: a day in single mode, both ends of a range. The event the panel closes on — bind it for "the user has finished choosing" rather than inspecting a half-picked 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.control.sizeGOG_CONFIG.control.errorDisplayGOG_CONFIG.control.clearableGOG_CONFIG.floatLabel.variantGOG_CONFIG.floatLabel.showPlaceholderGOG_CONFIG.dropdown.appendToBodyGOG_CONFIG.dropdown.directionGOG_CONFIG.datepicker.localeGOG_CONFIG.datepicker.firstDayOfWeekGOG_CONFIG.datepicker.formatGOG_CONFIG.labels.clearDateGOG_CONFIG.labels.openCalendarGOG_CONFIG.labels.today — and the rest of Calendar’s labels, once the panel is openEvery CSS custom property the datepicker paints with. The grid in its panel is themed by gog-calendar's tokens. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.
| Token | Description |
|---|---|
--gog-datepicker-label-color / -label-font-family / -label-font-size / -label-font-weight / -label-letter-spacing / -label-line-height / -label-text-transform | Field label. Each aliases its --gog-field-label-* counterpart. |
--gog-datepicker-field-bg / -border-color / -text-color | Field surface, border and text. |
--gog-datepicker-radius / -min-width | Field corner radius and minimum width. |
--gog-datepicker-focus-ring-color / -focus-ring-width / -hover-border-color | Focus and hover states. |
--gog-datepicker-icon-color / -icon-hover-color / -toggle-icon-size | The calendar toggle icon. |
--gog-datepicker-panel-bg / -panel-border-color / -panel-shadow / -panel-radius | The panel wrapping the calendar. The grid itself is themed by --gog-calendar-*. |
--gog-datepicker-panel-width | Width of the dropdown panel, max-content by default. Inline mode has no panel — it is gog-calendar on its own, so it sizes from --gog-calendar-max-width. |
--gog-datepicker-clear-color / -clear-icon-ratio / -actions-inset | Clear button color, glyph size and inset. |
--gog-datepicker-error-color / -error-border-color / -error-font-size | Validation error message and border. |
--gog-datepicker-float-label-reserve / -in-top / -over-gap / -over-reserve | Float-label geometry, derived from the shared --gog-field-float-label-* scale. |