Skip to main content

Datepicker

The baseline is a native <input type="date"> styled with Semetrika's existing input styles, giving consumers a fully accessible, keyboard-operable date picker with zero JavaScript. Adding any data-datepicker-* attribute opts in to a split fields mode that renders three <select> dropdowns (day, month, year) in the user's locale order while keeping the hidden original input in sync for form submission.

Usage​

When to use

  • Any form field collecting a single calendar date
  • When the project wants consistent styling across browsers' native date pickers
  • When split-field entry is needed for accessibility or mobile ergonomics - opt in via data-datepicker-*

When not to use

  • For date ranges - use two datepickers or a range component
  • For free-form date parsing from arbitrary strings - use a text input with server-side parsing
  • For time-only input - use a timepicker component

Do

  • Always start from the native <input type="date"> baseline
  • Provide min, max, and required as needed - they validate both the native and enhanced modes
  • Set data-datepicker-order="auto" (default) to pick the locale-appropriate field order

Don't

  • Don't build a custom calendar popup - defer to the browser
  • Don't remove the hidden ISO date input in enhanced mode; the server depends on it
  • Don't use placeholder-only labels - each of the three fields needs a real <label> element

API​

Slots​

SlotRequiredDescription
labelYesVisible label text for the datepicker.
helper-Helper text rendered below the input.

Props​

PropTypeDefaultDescription
idstring-HTML id of the input, used to associate the label. Auto-generated when omitted.
valuestring-Pre-filled date value in YYYY-MM-DD format.
minstring-Minimum selectable date in YYYY-MM-DD format.
maxstring-Maximum selectable date in YYYY-MM-DD format.
is_disabledboolean-Renders the disabled attribute on the input.
is_requiredboolean-Renders the required attribute on the input.
is_invalidboolean-Marks the control as invalid. Renders aria-invalid="true" when set.
helper_idstring-ID applied to the helper element; the input references it via aria-describedby.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.

Attributes​

AttributeSet byRequiredDescription
data-datepicker-orderConsumer-Field order override for split-fields mode. Defaults to "auto" (locale-derived).
data-datepicker-day-labelConsumer-Visually-hidden label for the day select. Defaults to "Day".
data-datepicker-day-placeholderConsumer-Placeholder string shown in the day select before a value is chosen. Defaults to "--".
data-datepicker-month-labelConsumer-Visually-hidden label for the month select. Defaults to "Month".
data-datepicker-month-placeholderConsumer-Placeholder string shown in the month select before a value is chosen. Defaults to "--".
data-datepicker-year-labelConsumer-Visually-hidden label for the year select. Defaults to "Year".
data-datepicker-year-placeholderConsumer-Placeholder string shown in the year select before a value is chosen. Defaults to "----".

Examples​

Sizes​

Sm, default, and lg variants stacked vertically. Font size and padding scale together.

Native​

Classless native <input type="date"> with default styling.

With min and max​

Validation attributes on the native baseline.

Disabled​

Disabled state, both native and enhanced.

Split fields​

data-datepicker-order="dmy" replaces the native control with three fields, entered day, month, then year.

Split fields locale order​

data-datepicker-order="auto" takes the field order from the browser's locale, so the same markup reads correctly wherever it is served.

Split fields explicit order​

Every supported order side by side, each pinned by its own data-datepicker-order value.

Invalid​

Validation error on the native control, flagged with aria-invalid and described by the helper text.

Accessibility​

  • WCAG 2.2 AA
  • Native baseline uses <input type="date"> semantics - keyboard and assistive tech supported by the browser.
  • Enhanced mode uses a <fieldset> with <legend> for the overall label.
  • Each of the three <select> fields has its own <label>.
  • Error messages linked via aria-describedby, propagated from the original input onto the fieldset and every field

Progressive enhancement​

  • No JS: native <input type="date"> works normally with the browser-provided picker, keyboard support, and validation via min, max, required.
  • With JS: reading any data-datepicker-* attribute switches to split-fields mode. JS hides (but keeps in the DOM) the original input, composes the ISO date on change, and populates the three fields from the hidden input on load.
  • How to enable: add any data-datepicker-* attribute to the native input. Semetrika's JS bundle auto-initializes.