Skip to content

x-date-picker.md

Latest commit

 

History

History
201 lines (146 loc) · 9.52 KB

x-date-picker.md

File metadata and controls

201 lines (146 loc) · 9.52 KB
Raw

x-date-picker

A calendar date picker with single-date and date-range modes. Renders a text input that opens a floating calendar panel. Dates are represented as ISO 8601 strings (YYYY-MM-DD).

Tag

<x-date-picker></x-date-picker>

Attributes

Attribute Type Default Description
mode enum "single" Selection mode: single range
value string — Selected date in YYYY-MM-DD format (single mode)
start string — Range start date in YYYY-MM-DD format (range mode)
end string — Range end date in YYYY-MM-DD format (range mode)
min string — Minimum selectable date (YYYY-MM-DD)
max string — Maximum selectable date (YYYY-MM-DD)
format enum "iso" Display format: iso (YYYY-MM-DD) or localized (via Intl)
locale string — BCP 47 locale tag for localized formatting (e.g. "en-US")
separator string " - " String placed between start and end in range display
auto-swap boolean false Automatically swap start/end when end is selected before start
range-allow-same-day boolean false Allow start and end to be the same date in range mode
close-on-select boolean false Close the calendar after a date is selected (or range is complete)
placeholder string — Input placeholder text
disabled boolean false Disables the input and calendar
readonly boolean false Input is read-only; calendar can still open but not select
required boolean false Marks the field as required
name string — Form field name
autocomplete string — HTML autocomplete hint
error string — Inline validation message; shows the error part and marks the field invalid
aria-label string — Accessible label for the input
aria-describedby string — References a describing element

Properties

Property Type Reflects attribute
mode string mode
value string value
start string start
end string end
disabled boolean disabled
readOnly boolean readonly
required boolean required
open boolean open
error string error

Events

Event Cancelable Detail Description
x-date-picker-input no { value, mode } Fired on each user text input
x-date-picker-change-request yes { value?, date?, start?, end?, mode, reason } Fired before committing a date selection
x-date-picker-change no { value?, start?, end?, mode, reason } Fired after the selection is committed

reason is one of "click", "keyboard", "blur", or "programmatic". In single mode, value contains the ISO date string. In range mode, start and end contain the ISO date strings (either may be absent if the range is incomplete).

Clearing by emptying the input

Deleting the text and committing (blur, Enter, or commit()) clears the committed value, exactly as clear() does. It fires a cancelable x-date-picker-change-request first, then x-date-picker-change, both with empty strings in the value fields — { value: "", mode, reason } in single mode, { start: "", end: "", mode, reason } in range mode. Cancelling the request keeps the committed value and restores the input text.

Committing a blank input when nothing is committed yet is a no-op: neither event fires.

Slots

Slot Description
(default) No default slot content expected

Accessibility

  • The text input has role="combobox" with aria-expanded (synced to open state) and aria-haspopup="dialog".
  • The calendar panel has role="dialog" with aria-modal="true".
  • The month label has aria-live="polite" for screen reader announcements.
  • Calendar day cells have role="gridcell" with aria-selected and aria-disabled.
  • A screen-reader status region (aria-live="polite", aria-atomic="true") is provided.
  • Full keyboard navigation within the calendar grid with roving tabindex.
  • When the error attribute is set, the input gets aria-invalid="true" and its aria-describedby points at the error part (appended to any author-supplied aria-describedby). The error part is an assertive live region (role="alert") so screen readers announce the validation message.

Form participation

x-date-picker is a form-associated custom element (via ElementInternals). In a <form>:

  • The committed value is submitted under its name: the ISO date in single mode, or start/end once a range is complete.
  • Constraint validation is honoured: a required picker with no committed date reports valueMissing and blocks submission; setting the error attribute reports a customError. This is what x-form and native submission gate on.
  • form.reset() clears the committed value(s) (mirroring how x-form-field resets) and drops the error attribute, so a stale validation message does not survive the reset. <fieldset disabled> disables it via formDisabledCallback.

Validation API

Like a native form control, x-date-picker exposes read-only validity, validationMessage, willValidate, form and labels, plus checkValidity() and reportValidity(). All seven delegate to the element's ElementInternals, so el.checkValidity() answers the same question a submit attempt would.

Keyboard (calendar open)

Key Action
ArrowLeft Move one day back
ArrowRight Move one day forward
ArrowUp Move one week back
ArrowDown Move one week forward
PageUp Move one month back
PageDown Move one month forward
Home Go to first day of week
End Go to last day of week
Enter/Space Select focused date
Escape Close calendar without selecting
Click outside Close calendar without selecting

Examples

Single date

<x-date-picker placeholder="Select a date"></x-date-picker>

Date range

<x-date-picker mode="range" placeholder="Select date range"></x-date-picker>

Pre-selected value

<x-date-picker value="2026-03-18"></x-date-picker>

Bounded range

<x-date-picker min="2026-01-01" max="2026-12-31"></x-date-picker>

Localized display

<x-date-picker format="localized" locale="en-US" placeholder="Pick a date"></x-date-picker>

Disabled

<x-date-picker disabled placeholder="Not available"></x-date-picker>

Validation error

The error attribute renders an inline message below the field and marks it invalid. Inside x-form, this is driven for you by form.setFieldError(name, message).

<x-date-picker name="dob" error="Please enter a valid date"></x-date-picker>

Clear it by removing the attribute (or el.error = ''). Style the message via the error CSS part or the --x-date-picker-error-color custom property.

Listening to changes

document.querySelector('x-date-picker').addEventListener('x-date-picker-change', e => {
  console.log('selected date:', e.detail.value);
});

ClojureScript (hiccup renderer)

[:x-date-picker {:placeholder "Select a date"
                 :on-x-date-picker-change
                 (fn [e] (swap! state assoc :date (.. e -detail -value)))}]

[:x-date-picker {:mode "range"
                 :placeholder "Select date range"
                 :on-x-date-picker-change
                 (fn [e]
                   (swap! state assoc
                          :start (.. e -detail -start)
                          :end   (.. e -detail -end)))}]