Date Picker

Date Picker widgets are Input Fields that let the user enter a date in a single compact field: they can type it using their keyboard or open a drop-down calendar popover to select it visually. For an always-visible inline variant, use the Calendar.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.datePicker('startDate', {
    label: 'Start Date',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "datePicker",
      "path": "startDate",
      "label": "Start Date"
    }
  ]
}

Props

Use these props to customize your Date Picker widget.

prop	type	description
`disabledDateRangeMessage`	string \| Localizable	Error message shown when a typed date falls inside a disabled range
`disabledRanges`	array	Array of `{ start: string, end?: string }` ISO date ranges whose days render disabled
`hint`	string	A description to display below the input fields
`icon`	string	Custom icon class to display inside the input visually (e.g. `fas fa-calendar`)
`invalidDateMessage`	string \| Localizable	Error message shown when the typed date does not exist, e.g. February 30
`maxDate`	string	Latest allowed date (ISO date, inclusive); later calendar days render disabled
`maxDateMessage`	string \| Localizable	Error message shown when a typed date is after `maxDate`
`minDate`	string	Earliest allowed date (ISO date, inclusive); earlier calendar days render disabled
`minDateMessage`	string \| Localizable	Error message shown when a typed date is before `minDate`
`nextMonthAriaLabel`	string	ARIA label for the next month button
`nextMonthIcon`	string	Custom CSS class for the “next month” button inside the calendar
`numberOfMonths`	number	Number of months to display simultaneously in the popover. Defaults to 1
`prevMonthAriaLabel`	string	ARIA label for the previous month button
`prevMonthIcon`	string	Custom CSS class for the “previous month” button inside the calendar

Hint

Use the property hint to add descriptive text.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.datePicker('startDate', {
    hint: 'Provide a start date to calculate your quote.',
    label: 'Start Date',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "datePicker",
      "path": "startDate",
      "label": "Start Date",
      "props": {
        "hint": "Provide a start date to calculate your quote."
      }
    }
  ]
}

Icon

Use the property icon to add an icon, which appears next to the toggle chevron.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.datePicker('startDate', {
    icon: 'calendar_month',
    label: 'Start Date',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "datePicker",
      "path": "startDate",
      "label": "Start Date",
      "props": {
        "icon": "calendar_month"
      }
    }
  ]
}

Custom Icons

Use the properties prevMonthIcon, nextMonthIcon, prevMonthAriaLabel, and nextMonthAriaLabel to customize the navigation buttons within the calendar popover.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.datePicker('date', {
    prevMonthIcon: 'chevron_left',
    nextMonthIcon: 'chevron_right',
    prevMonthAriaLabel: 'Go to previous month',
    nextMonthAriaLabel: 'Go to next month',
    label: 'Custom Icons Date Picker',
    uid: 'date-picker-icons',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "uid": "date-picker-icons",
      "kind": "input",
      "type": "datePicker",
      "path": "date",
      "label": "Custom Icons Date Picker",
      "props": {
        "prevMonthIcon": "chevron_left",
        "nextMonthIcon": "chevron_right",
        "prevMonthAriaLabel": "Go to previous month",
        "nextMonthAriaLabel": "Go to next month"
      }
    }
  ]
}

Min, Max and Disabled Dates

Use minDate and maxDate (ISO dates, both inclusive) to bound the selectable range, and disabledRanges to disable specific date blocks. Out-of-range days render disabled in the calendar popover, and a typed date that violates a boundary raises an input error; customize (and localize) the messages with minDateMessage, maxDateMessage and disabledDateRangeMessage.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.datePicker('appointmentDate', {
    hint: 'Appointments between 2026-02-01 and 2026-07-31',
    minDate: '2026-02-01',
    maxDate: '2026-07-31',
    disabledRanges: [
      {
        start: '2026-02-09',
        end: '2026-02-10',
      },
      {
        start: '2026-02-17',
      },
    ],
    minDateMessage: 'No appointments before February 2026',
    maxDateMessage: 'No appointments after July 2026',
    disabledDateRangeMessage: 'This date is not available',
    label: 'Appointment Date',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "datePicker",
      "path": "appointmentDate",
      "label": "Appointment Date",
      "props": {
        "hint": "Appointments between 2026-02-01 and 2026-07-31",
        "minDate": "2026-02-01",
        "maxDate": "2026-07-31",
        "disabledRanges": [
          {
            "start": "2026-02-09",
            "end": "2026-02-10"
          },
          {
            "start": "2026-02-17"
          }
        ],
        "minDateMessage": "No appointments before February 2026",
        "maxDateMessage": "No appointments after July 2026",
        "disabledDateRangeMessage": "This date is not available"
      }
    }
  ]
}

Number of Months

Use the property numberOfMonths to display multiple months side-by-side in the calendar popover.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.datePicker('appointmentDate', {
    hint: 'The popover shows two months side by side',
    numberOfMonths: 2,
    label: 'Appointment Date',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "datePicker",
      "path": "appointmentDate",
      "label": "Appointment Date",
      "props": {
        "hint": "The popover shows two months side by side",
        "numberOfMonths": 2
      }
    }
  ]
}

Invalid Date

Use the property invalidDateMessage to customize (and localize) the error shown when the typed segments don’t form a real calendar date, such as February 30 or the 13th month.

import { gui } from '@golemui/gui-shared';

export default [
  gui.inputs.datePicker('birthDate', {
    hint: 'Type a date that doesn\'t exist, e.g. February 30',
    invalidDateMessage: 'Please enter a real calendar date',
    label: 'Birth Date',
  }),
];

{
  "$schema": "https://golemui.com/schemas/form.schema.json",
  "form": [
    {
      "kind": "input",
      "type": "datePicker",
      "path": "birthDate",
      "label": "Birth Date",
      "props": {
        "hint": "Type a date that doesn't exist, e.g. February 30",
        "invalidDateMessage": "Please enter a real calendar date"
      }
    }
  ]
}

Styling

Date Pickers can be styled as explained in the Styling Guide. The typed field and the popover calendar each have their own styling variables.

CSS Variables

Following you will find a list with the CSS Variables specific to the Date Picker popover positioning and toggle.

CSS Variable	Description
`--gui-radius-md`	Interactive calendar container and day button border radius
`--gui-bg-default`	Interactive calendar background color
`--gui-border-default`	Interactive calendar border color
`--gui-space-3`	Internal padding within the calendar view and day buttons
`--gui-text-default`	Input text color and day buttons text color
`--gui-bg-disabled`	Disabled day background color
`--gui-intent-primary`	Selected day background color
`--gui-intent-primary-hover`	Today’s day border color
`--gui-border-default`	Hover day border color

Anatomy

This is the anatomy of the Date Picker Widget in case you want to use your CSS styles.

<div class="gui-form">
  <gui-date-picker>
    <label for="fieldUid">
      Label
      <div class="gui-date__hint" id="fieldUid_hint">Hint</div>
    </label>

    <div class="gui-widget" aria-expanded="true">
      <div class="gui-date-input gui-calendar--icon" role="group">

        <div class="gui-date-input__touch-target">
          <input type="text" inputmode="numeric" class="gui-date-input__part" data-type="month" maxlength="2" placeholder="mm" tabindex="0" value="12">
          <div class="gui-date-input__visual-underline"></div>
        </div>
        <span class="gui-date-input__separator">/</span>

        <div class="gui-date-input__touch-target">
          <input type="text" inputmode="numeric" class="gui-date-input__part" data-type="day" maxlength="2" placeholder="dd" tabindex="-1" value="25">
          <div class="gui-date-input__visual-underline"></div>
        </div>
        <span class="gui-date-input__separator">/</span>

        <div class="gui-date-input__touch-target">
          <input type="text" inputmode="numeric" class="gui-date-input__part gui-date-input__year" data-type="year" maxlength="4" placeholder="yyyy" tabindex="-1" value="2024">
          <div class="gui-date-input__visual-underline"></div>
        </div>

      </div>

      <span class="gui-widget-icon fas fa-calendar-alt"></span>

      <gui-calendar>
        <div class="gui-calendar-input">
          <div class="gui-calendar__header">
            <button class="gui-button gui-calendar__month-button gui-calendar__month-button--prev" type="button"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 256 256"><path d="M181.66,133.66l-80,80a8,8,0,0,1-11.32-11.32L164.69,128,90.34,53.66a8,8,0,0,1,11.32-11.32l80,80A8,8,0,0,1,181.66,133.66Z"></path></svg></button>
            <span aria-live="polite">December 2024</span>
            <button class="gui-button gui-calendar__month-button gui-calendar__month-button--next" type="button"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 256 256"><path d="M181.66,133.66l-80,80a8,8,0,0,1-11.32-11.32L164.69,128,90.34,53.66a8,8,0,0,1,11.32-11.32l80,80A8,8,0,0,1,181.66,133.66Z"></path></svg></button>
          </div>
          <div class="gui-calendar__days-grid" role="grid">
            <!-- Calendar grid -->
          </div>
        </div>
      </gui-calendar>
    </div>
  </gui-date-picker>
</div>