<exm-date-picker>

@exmg/exm-date-picker

Material 3 styled date picker, built with Lit, @material/web and cally. The package contains two kinds of components:

• <exm-date-picker>: the calendar panel on its own, for use in your own popover or dialog.
• <exm-outlined-date-picker> / <exm-filled-date-picker>: a Material text field with a trailing calendar icon that opens the picker in a menu. These variants are form associated and validate through the platform form APIs.

The picker supports a month/year heading with a 24-year grid for quick year selection, keyboard navigation, and optional Cancel / Ok confirmation buttons.

Installation

bun add @exmg/exm-date-picker

Peer dependencies: lit, @exmg/lit-base, tslib. @material/web, cally and luxon are regular dependencies.

Example Usage

<script type="module">
  import '@exmg/exm-date-picker/exm-date-picker.js';
</script>

<exm-date-picker value="2026-09-12"></exm-date-picker>

The form input variants:

<script type="module">
  import '@exmg/exm-date-picker/exm-outlined-date-picker.js';
  import '@exmg/exm-date-picker/exm-filled-date-picker.js';
</script>

<exm-outlined-date-picker
  name="date"
  label="Select Date"
  format="MM-dd-yyyy"
  timezone="America/New_York"
  supporting-text="Choose a date from the calendar."
  required
  ?confirm-input
></exm-outlined-date-picker>

<exm-filled-date-picker name="date-2" value="1760000000000"></exm-filled-date-picker>

Choosing the right variant

| Element | Use when | | ------------------------------ | ------------------------------------------------------------------------------- | | exm-date-picker | You want the bare calendar panel inside your own overlay, popover or layout. | | exm-outlined-date-picker | You want an outlined Material text field that opens the picker from a menu. | | exm-filled-date-picker | Same, but with the filled Material text field style. |

API

<exm-date-picker>

Properties/Attributes

| Name | Type | Default | Description | | ---------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------- | | value | string | '' | Selected date as an ISO date string (yyyy-mm-dd). | | locale | string | None | Locale used for the month/year heading (e.g. nl-NL). Defaults to en-US when unset. | | min | number | None | Minimum selectable date as a millisecond timestamp. Days before it are not selectable. | | max | number | None | Maximum selectable date as a millisecond timestamp. Days after it are not selectable. | | title | string | '' | Optional headline shown above the calendar. | | confirmInput | boolean | None | Attribute: confirm-input. Shows Cancel / Ok buttons; Ok fires date-change. When false, selecting a date fires date-change immediately. | | firstDayOfWeek | number | 0 | First day of the week: 0 = Sunday ... 6 = Saturday. |

Events

| Name | Detail | Description | | ------------- | -------- | -------------------------------------------------------------------------------------------------------- | | date-change | string | Fired when a date is selected (or Ok is clicked with confirm-input). detail is the ISO date string. | | date-cancel | string | Fired when Cancel is clicked with confirm-input. detail is the current ISO date string. |

Both events bubble and are composed. When confirm-input is set, date-change fires from the Ok button and date-cancel from the Cancel button; without it, date-change fires as soon as a day is selected.

CSS Custom Properties

| Name | Description | | ------------------------------- | --------------------------------------------- | | --md-sys-color-primary | Selected/active color (heading, buttons). | | --md-sys-color-on-primary | Text/icon color on primary surfaces. | | --md-sys-color-on-surface | Main text color (heading, year grid). | | --md-sys-color-on-surface-variant | Secondary text color. | | --md-sys-color-surface-container-highest | Surface color of the year grid background. | | --exm-date-picker-inline-padding | Inline padding of the picker panel. |

<exm-outlined-date-picker> / <exm-filled-date-picker>

Form associated Material text field with a trailing calendar icon button. Clicking the icon opens the picker in an md-menu popover anchored to the field. The field also accepts a typed date in format.

The picker inside the menu is an exm-date-picker; its min, max and locale are synced from the input component.

Properties/Attributes

| Name | Type | Default | Description | | ---------------- | --------- | -------------- | ------------------------------------------------------------------------------ | | value | number | None | Selected date as a millisecond timestamp. Submitted to the form as a string. | | name | string | None | Form control name. | | label | string | 'Select Date'| Field label, also used as the picker title. | | format | string | 'dd-MM-yyyy' | Display and parse format (Luxon tokens), e.g. MM-dd-yyyy. | | locale | string | 'en-US' | Locale used for parsing/formatting and the picker heading. | | timezone | string | 'local' | IANA timezone string (e.g. America/New_York) or local. | | closeOnSelect | boolean | true | Attribute: close-on-select. Closes the menu when a date is selected. | | disabled | boolean | false | Disables the field and blocks opening the picker. | | required | boolean | false | Marks the control as required for form validation. | | supportingText | string | '' | Attribute: supporting-text. Helper text below the field. | | min | number | None | Minimum allowed date as a millisecond timestamp. | | max | number | None | Maximum allowed date as a millisecond timestamp. | | confirmInput | boolean | None | Attribute: confirm-input. Passed through to the embedded picker. |

Events

| Name | Detail | Description | | -------- | -------- | ---------------------------------------------------------------------------------------------------- | | change | number | Fired when the value changes: a date selected in the picker or a valid date typed in the field. detail is the millisecond timestamp. |

change is a composed, non-bubbling CustomEvent. Note that the date picker's own date-change and date-cancel events are handled internally by the input components.

Form association and validation

The input variants are form associated (static formAssociated = true) and integrate with the platform form APIs:

• The value is submitted as a string via FormData under name.
• Validation covers required, min (range underflow) and max (range overflow), with default messages Please select a date, Date must be on or after ... and Date must be on or before ....
• checkValidity() and reportValidity() are available; reportValidity() clears the error state when the control is valid. The browser's built-in invalid UI bubble is suppressed in favor of the Material error text on the field.
• The component exposes dateTime (a Luxon DateTime or undefined) and displayValue (the formatted string) as read-only getters.