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, andrequiredas 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
| Slot | Required | Description |
|---|---|---|
label | Yes | Visible label text for the datepicker. |
helper | - | Helper text rendered below the input. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | - | HTML id of the input, used to associate the label. Auto-generated when omitted. |
value | string | - | Pre-filled date value in YYYY-MM-DD format. |
min | string | - | Minimum selectable date in YYYY-MM-DD format. |
max | string | - | Maximum selectable date in YYYY-MM-DD format. |
is_disabled | boolean | - | Renders the disabled attribute on the input. |
is_required | boolean | - | Renders the required attribute on the input. |
is_invalid | boolean | - | Marks the control as invalid. Renders aria-invalid="true" when set. |
helper_id | string | - | ID applied to the helper element; the input references it via aria-describedby. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-datepicker-order | Consumer | - | Field order override for split-fields mode. Defaults to "auto" (locale-derived). |
data-datepicker-day-label | Consumer | - | Visually-hidden label for the day select. Defaults to "Day". |
data-datepicker-day-placeholder | Consumer | - | Placeholder string shown in the day select before a value is chosen. Defaults to "--". |
data-datepicker-month-label | Consumer | - | Visually-hidden label for the month select. Defaults to "Month". |
data-datepicker-month-placeholder | Consumer | - | Placeholder string shown in the month select before a value is chosen. Defaults to "--". |
data-datepicker-year-label | Consumer | - | Visually-hidden label for the year select. Defaults to "Year". |
data-datepicker-year-placeholder | Consumer | - | 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 viamin,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.
Related
- textfield - shared input styling tokens
- timepicker - sibling component for time-only input