GUILD OF GLEKS UIv21.19.0

gog-datepicker

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.

Overview

Import the component and drop it into a template.

typescript
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>

Examples

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" />
}

States

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.

Choose a date
<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

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 />

Width

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" />

No visible label

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" />

A single date

[(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>

Range

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 — gogDateSelect21.15.0 is the event that waits for both ends.

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>

Bounds and disabled dates

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" />

Time

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 />

Typing — one pattern, both directions

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" />

Locale

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 labels

The field's own openCalendarLabel and clearAriaLabel, plus the nine strings of the calendar inside it 21.15.0 — the footer buttons, the four navigation arrows and the three time fields — so one field can be named in another language than the app's config says. Open it: the arrows read German.

<!-- 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"
/>

The panel — 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

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.

November 2026
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>

Float label

'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"
/>

Reactive forms

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>

App-wide defaults — 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" />

Accessibility

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.

  • Keyboard — from the field, ↓ or Enter opens the panel. Esc closes it from anywhere inside — the calendar button and the day grid included — and returns focus to the field. In the grid the arrows move by a day and a week, Home/End to the ends of the week, PageUp/PageDown change the month and with Shift the year, and Enter or Space picks. The 42 day cells are one tab stop.
  • Fixed in 21.15.021.15.0 — Escape closed the panel only from the text input, and the arrows moved the highlight while the focus ring, and a screen reader, stayed on the day they had left.
  • Name — label or ariaLabel; the calendar button is named by openCalendarLabel, the clear button by clearAriaLabel.
  • Error — errorMessage sets aria-invalid and links the message with aria-describedby.

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 field picks one day or a start/end pair.
formatstring | nullGOG_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.
localestringGOG_CONFIG.datepicker.locale ?? 'en-US'BCP-47 tag driving month and weekday names, through Intl.
firstDayOfWeeknumberGOG_CONFIG.datepicker.firstDayOfWeek ?? from the locale0 = Sunday … 6 = Saturday.
min / maxDate | nullnullSelectable bounds.
disabledDates((date: Date) => boolean) | nullnullExtra exclusions as a predicate — an array cannot express "weekends".
defaultMonthDate | nullnullWhich month the panel opens on when there is no selection yet.
numberOfMonthsnumber1Months shown side by side. Two is what makes a range picker usable.
showTimebooleanfalseAdds a clock under the grid.
hourFormat / minuteStep / showSeconds'12' | '24' / number / boolean'24' / 1 / falseHow that clock is configured.
showTodayButton / showThisMonthButtonbooleantrue / falseTwo separate footer actions: "Today" SELECTS today; "This month" only moves the view back.
todayLabel / thisMonthLabel / openCalendarLabel / clearAriaLabelstring'Today' / 'This month' / 'Open calendar' / 'Clear date'Wording for the footer actions and the two icon buttons.
previousMonthLabel / nextMonthLabel / previousYearLabel / nextYearLabel / hoursLabel / minutesLabel / secondsLabel21.15.0string | undefinedGOG_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.
allowTextInputbooleantrueWhether 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.
inlinebooleanfalseRenders the calendar always-visible, with no field. Literally gog-calendar on its own.
clearablebooleanGOG_CONFIG.control.clearable ?? falseA clear button, shown only once a date is set.
label / ariaLabel / placeholder / inputIdstring''Field label, accessible name, placeholder, and an id for an external <label>.
floatLabel / floatLabelShowPlaceholder'none' | 'in' | 'on' | 'over' / booleanGOG_CONFIG.floatLabel.* ?? 'none' / falseFloat-label variant and whether the placeholder reappears once it has floated.
errorMessage / errorDisplaystring / 'manual' | 'auto''' / GOG_CONFIG.control.errorDisplay ?? 'manual'Validation message, shown manually or derived from the bound form control.
size / disabled / fullWidthGogSize / boolean / booleanGOG_CONFIG.control.size ?? 'md' / false / trueDensity, disabled state, and how the field sizes itself.
appendToBody / dropdownDirection / dropdownZIndexboolean / GogDropdownDirection / number | nullGOG_CONFIG.dropdown.* ?? component defaultsPanel placement. appendToBody renders it into <body> so an overflow-clipped ancestor cannot cut it off.

Outputs

NamePayloadDescription
valueChangeDate | GogDateRange | nullEmitted when the value changes — including a half-picked range and typed text. Comes from the value model input.
gogDateSelect21.15.0GogDatepickerValueA 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.

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.control.size
  • GOG_CONFIG.control.errorDisplay
  • GOG_CONFIG.control.clearable
  • GOG_CONFIG.floatLabel.variant
  • GOG_CONFIG.floatLabel.showPlaceholder
  • GOG_CONFIG.dropdown.appendToBody
  • GOG_CONFIG.dropdown.direction
  • GOG_CONFIG.datepicker.locale
  • GOG_CONFIG.datepicker.firstDayOfWeek
  • GOG_CONFIG.datepicker.format
  • GOG_CONFIG.labels.clearDate
  • GOG_CONFIG.labels.openCalendar
  • GOG_CONFIG.labels.today — and the rest of Calendar’s labels, once the panel is open

Styling Tokens

Every 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.

TokenDescription
--gog-datepicker-label-color / -label-font-family / -label-font-size / -label-font-weight / -label-letter-spacing / -label-line-height / -label-text-transformField label. Each aliases its --gog-field-label-* counterpart.
--gog-datepicker-field-bg / -border-color / -text-colorField surface, border and text.
--gog-datepicker-radius / -min-widthField corner radius and minimum width.
--gog-datepicker-focus-ring-color / -focus-ring-width / -hover-border-colorFocus and hover states.
--gog-datepicker-icon-color / -icon-hover-color / -toggle-icon-sizeThe calendar toggle icon.
--gog-datepicker-panel-bg / -panel-border-color / -panel-shadow / -panel-radiusThe panel wrapping the calendar. The grid itself is themed by --gog-calendar-*.
--gog-datepicker-panel-widthWidth 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-insetClear button color, glyph size and inset.
--gog-datepicker-error-color / -error-border-color / -error-font-sizeValidation error message and border.
--gog-datepicker-float-label-reserve / -in-top / -over-gap / -over-reserveFloat-label geometry, derived from the shared --gog-field-float-label-* scale.