Date Field
Date fields capture a single calendar date with locale-aware formatting and an optional calendar popup for pointer input.
Try it
Usage
Compose the input, calendar trigger, popup, and calendar as children of RuiDateField. When no children are supplied, RuiDateField renders this same composition for you. Bind value as an ISO YYYY-MM-DD string and use dateStyle to control the formatted value.
import {
RuiDateField,
RuiDateFieldCalendar,
RuiDateFieldControl,
RuiDateFieldInput,
RuiDateFieldPopover,
RuiDateFieldToggle,
} from '@ecopages/radiant-ui/date-field';
import { RuiField } from '@ecopages/radiant-ui/field';
import { RuiLabel } from '@ecopages/radiant-ui/label';
<RuiField name="startDate">
<RuiLabel>Start date</RuiLabel>
<RuiDateField value="2026-08-07" dateStyle="medium">
<RuiDateFieldControl>
<RuiDateFieldInput />
<RuiDateFieldToggle />
</RuiDateFieldControl>
<RuiDateFieldPopover>
<RuiDateFieldCalendar />
</RuiDateFieldPopover>
</RuiDateField>
</RuiField>Calendar input
Use the calendar button to choose a date instead of typing. When the popup opens, focus moves to the selected date or the first available date. This example uses a two-month popup for dates near a month boundary.
Masked entry
masked guides segment-by-segment typing. Disable it when users paste full ISO strings from external tools.
Bound the range
Set min and max to prevent invalid bookings. The embedded calendar inherits the same constraints.
Theming
Date Field surfaces map to semantic surface roles, never Tailwind palette steps:
| Part | CSS roles |
|---|---|
Control group (rui-date-field__group) | border, background, radius-control; focus-ring ring on focus-within |
| Input text | on-background, --text-control, --space-control-* |
| Placeholder | on-surface + opacity-muted |
| Disabled | opacity-disabled |
Invalid (aria-invalid) | error border |
Popup (rui-date-field__popover) | popover surface + shadow-overlay (via rui-popover) |
Geometry shares control tokens (--size-control-*, --radius-control, --space-control-*) with RuiInput and RuiButton so form rows align. Override at the theme layer, not in component CSS.
API
RuiDateField is a custom element (<rui-date-field>) that coordinates its light-DOM input, toggle button, and calendar popover.
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
value | string | '' | Canonical ISO YYYY-MM-DD value. |
min | string | '' | Earliest selectable ISO date. |
max | string | '' | Latest selectable ISO date. |
disabled | boolean | false | Disable the field and calendar. |
read-only | boolean | false | Disable editing while keeping the value visible. |
label | string | '' | Accessible name when there is no associated RuiLabel. |
name | string | '' | Native name for the underlying input. |
placeholder | string | locale default | Overrides the locale-derived placeholder. |
locale | string | '' | BCP 47 locale tag, or comma-separated fallback list. |
date-style | short · medium · long · full | medium | How the committed value is displayed when not editing. |
masked | boolean | true | Guide digits with a locale mask while typing. |
visible-months | number | 1 | Month grids shown in the calendar popover. |
Events
| Event | Detail | Description |
|---|---|---|
rui-change | { value } | Fired when a valid date is committed (typing or calendar pick). |
Composition helpers
Pass these helpers as RuiDateField children when the default structure is not enough:
| Helper | Renders |
|---|---|
RuiDateFieldControl | Bordered control row containing the input and trigger. |
RuiDateFieldInput | Locale-aware text input managed by the date-field host. |
RuiDateFieldToggle | Button that opens and closes the calendar popup. |
RuiDateFieldPopover | Popup shell for the calendar. |
RuiDateFieldCalendar | RuiCalendar synchronized with the field value and constraints. |
CSS classes
Public BEM classes on the composed light-DOM surface (documented via @cssclass on RuiDateField):
| Class | Description |
|---|---|
.rui-date-field | Root surface. |
.rui-date-field__group | Bordered control-height row wrapping input and toggle. |
.rui-date-field__input | The masked / formatted text input. |
.rui-date-field__popover | Calendar popup shell (rui-popover / rui-floating). |
Theme roles
| Part | CSS variables consumed |
|---|---|
| Control group | --border, --background, --radius-control, --focus-ring |
| Input text | --on-background, --text-control, --space-control-x, --space-control-y |
| Placeholder | --on-surface, --opacity-muted |
| Disabled | --opacity-disabled |
| Invalid | --error |
| Popup | --shadow-overlay (via rui-popover) |
Accessibility
- Pair every date field with a visible
RuiLabeloraria-label. - Invalid dates should surface through
RuiFielderror text, not color alone. - The trigger opens the popup and moves focus to the selected date or first available date; arrow keys move between days, Page Up / Page Down change months, and Escape closes the popup.