DatePicker

Dates without doubt.

Usage

Basic

The field is a text box with aria-haspopup="dialog", the chevron beside it is a labeled button, and the calendar is a role="grid" with Today and Clear links in its footer. Today carries aria-current="date" under the orange dot.

Range and report presets

Two clicks set a start and an end, and the preset column renders only in range mode, with aria-pressed on the active preset. Presets and the range value are properties, so setup writes them. The flat copy is the same picker with inline, so the column stays on the page.

Date and time

show-time adds a column of times beside the calendar, on the locale's clock unless hour-format names one. Picking a day keeps the time; picking a time closes the calendar. time-step spaces the rows and min-time and max-time bound the day. The value posts as a local YYYY-MM-DDTHH:mm with no time zone.

Format and locale

date-format is one of the four Intl dateStyle names, and locale supplies the order, the separators, the words, the first day of the week and the clock; the value stays ISO whatever the field shows. Unset, locale follows the page. first-day-of-week overrides the first day.

Typed entry

Type a date and press Enter or leave the field: the entry is read in the field format, as a month name, or as ISO, and rewritten in the field format once it commits. An entry that does not parse keeps its text, posts an empty value and holds the form on badInput with a message that shows the expected form.

Inline calendar

inline renders the calendar flat with no trigger and no shadow. It never opens, so it follows an external value write to the new month instead of leaving the date off screen.

As a property

variant="quiet" draws the date as text in the surrounding font, the calendar glyph before it, with no shell at rest: the fill comes on hover, and the shell while the field has focus or the calendar is open, since a focused text field is being typed into. The label is not drawn but still names the field.

Bounds and barred days

min-date and max-date stop the month arrows at the bounds, disabledDays bars weekdays by number and disabledDates bars single days; the last two are properties. A barred day stays in the grid with aria-disabled and stays reachable by the roving cursor, it just refuses the pick.

Sizes

size is the same sm, md, lg vocabulary and the same 28, 34, 42 heights as the rest of the control family, so a date field lines up in a row with a Select or an InputText. The calendar keeps its own metrics, and an inline picker has no field to size.

States

A trigger the user cannot open cannot be filled in, so a disabled picker never holds the form on valueMissing. An author-set error still applies and paints the trigger in the danger tone.

Read-only

readonly keeps the date readable but not typed over, opens no calendar, and the value still posts. A flat inline calendar shows its days and picks none.

In a form

A single date posts the ISO string whatever the field format, and a range posts "start,end". A cleared picker posts an empty string, and a disabled one is barred from submission and posts nothing at all.

Events

suiOpen fires after the element opens itself, suiMonthChange reports the month on show, and the cancelable suiClose fires before it closes and says why: escape, outside, trigger or pick. Here the listener refuses the first stray outside click with preventDefault and lets the next one through.

Keyboard

API

Theming

Every design token this element can render with, read from its own stylesheets and the ones it imports. Set a token on :root or on any ancestor and every use below follows it. The values shown are the ones in the theme you are viewing. The list is read per stylesheet, so an element that imports a shared drawing module lists that module's tokens too, whether or not it paints with all of them.

See also