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:

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

The Temporal API must be available at runtime. If your target browsers do not yet ship it natively, load a polyfill such as temporal-polyfill in your 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.

Methods

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

focus

Focus the date picker's text input.

validate

Re-run constraint validation and dispatch 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:

value-changed

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.

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