Date Picker

import "@taprootio/espalier/date-picker";

<esp-date-picker>

A date / datetime / time / range picker built on the browser-native Temporal API and the native Popover API. It participates in native <form> elements via ElementInternals, so its value is submitted with the form just like a built-in <input type="date">.

Wrap the picker in an esp-form-item for a label, validation messages, and consistent spacing with other Espalier form controls.

The picker supports four modes. Use the mode attribute to switch between a single date, a date-and-time, a time-only, or a date range:

For date range selection the value uses ISO 8601 interval notation (start/end). Click once to set the start, then click again to set the end. If the second click is before the first, the dates are automatically swapped:

Constrain the selectable range with min and max. Dates outside the range are greyed out and cannot be selected. The picker also reports rangeUnderflow / rangeOverflow through the Constraint Validation API:

To reach a distant date quickly, click the month or the year in the calendar header. The month opens a grid of the twelve months and the year opens a scrolling list of years; choosing one moves the calendar there without changing the value. The header arrows step by month on the day grid, by year on the month grid, and by a page on the year list, and Escape returns to the day grid:

Because the picker is form-associated, its value is included when the form is submitted and it responds to form resets:

Runtime requirement: The Temporal API must be available. If target browsers do not yet ship it natively, load a polyfill such as temporal-polyfill in the document <head> before using this component.

Attributes

<esp-date-picker> has the following attributes:

mode

mode has a default value of "date".

The picker mode.

Value	Behavior
`date`	Pick a single date
`datetime`	Pick a date and time
`time`	Pick a time only
`range`	Pick a start and end date

value

value has a default value of undefined.

ISO 8601 value string. The format depends on the current mode:

Mode	Format
`date`	`YYYY-MM-DD`
`datetime`	`YYYY-MM-DDTHH:mm:ss`
`time`	`HH:mm` or `HH:mm:ss`
`range`	`YYYY-MM-DD/YYYY-MM-DD` (ISO 8601)

placeholder

placeholder has a default value of "Select...".

Placeholder text shown when no value is set.

min

min has a default value of "".

The minimum selectable date as an ISO 8601 date string. Dates before this value are greyed out and cannot be selected. When the current value is earlier than min, the picker reports a rangeUnderflow validity error.

max

max has a default value of "".

The maximum selectable date as an ISO 8601 date string. Dates after this value are greyed out and cannot be selected. When the current value is later than max, the picker reports a rangeOverflow validity error.

disabled

disabled has a default value of false.

Disables the picker. When true, the trigger button cannot be clicked and the popover will not open. The picker also sets aria-disabled on its internals.

name

name has a default value of "".

The name used when the picker participates in a <form>. The selected value is submitted under this name.

required

required has a default value of false.

Makes the picker required for form validation. When true and no value is set, the picker reports a valueMissing validity error through the Constraint Validation API.

required-message

required-message has a default value of "".

A custom message to display when the picker is required but no date is selected. Defaults to "Please select a date." when not set.

intent

intent has a default value of undefined.

The element's intent — its meaning: neutral (no pin), or success, warning, danger, info — each pinned to its fixed status family (blue for info), retunable per theme via intents. On token-emitting controls a non-neutral intent pins the filled-action pair to that family, derived over the governing zone's theme; class-styled chrome (badges, callouts, status pills) opts out of inline emission and renders its treatment from CSS classes instead. An intent never repaints the surrounding zone, which is what contexts are for. Removing the attribute restores the element's own default intent.

context

context has a default value of undefined.

A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.

Methods

<esp-date-picker> has the following methods:

focus

Focus the date picker's text input.

validate

Re-run constraint validation and dispatch esp-validity-changed.

checkValidity

Check whether the current state is valid (delegates to ElementInternals).

traverseToClosest

Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.

Events

<esp-date-picker> emits the following events:

esp-value-changed

esp-value-changed is of type CustomEvent<string>.

Emitted when the user picks a date, time, or range. The event detail is the new ISO 8601 value string.

esp-validity-changed

esp-validity-changed is of type CustomEvent<{ valid: boolean; message: string }>.

Fired whenever constraint validation runs.

CSS Properties

<esp-date-picker> has the following CSS properties:

--esp-field-background

Background color of the shared field shell. Defaults to var(--esp-color-layer-2).

--esp-field-border-color

Border color of the shared field shell. Defaults to var(--esp-color-border).

--esp-field-border-width

Border width of the shared field shell. Defaults to 1px.

--esp-field-text-color

Text color used inside the shared field shell. Defaults to var(--esp-color-text).

--esp-field-hover-bg

Hover background color of the shared field shell. Derived from --esp-field-background.

--esp-field-focus-bg

Focus background color of the shared field shell. Derived from --esp-field-background.

--esp-field-focus-shadow

Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).