VERIFICATION-0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
The browser supplies its own date picker; typing the date also works.Date and time field
<forma-date-time-field>
Native date, time and datetime-local inputs in the .forma-field structure, keeping the platform picker and direct typed entry.
- Authoring tag
<forma-date-time-field>- Category
- Form inputs
- Behavior owner
- Native HTML
- Canonical source
patterns/date-time-field.html
Purpose
A date and time field collects a calendar date, a time of day, or both, using native input type="date", type="time" or type="datetime-local" inside the shared .forma-field structure (see Text field). The browser supplies the segmented typed entry, the picker, locale-appropriate display and min/max/step validation, while the submitted value is always the locale-independent ISO form (2026-10-14, 09:30, 2026-10-14T09:30). Forma styles the box; it does not draw its own calendar.
Use when
- The user enters one date, one time of day, or one local date and time.
- The allowed values have simple bounds (earliest or latest date, business hours, 15-minute slots) that
min,maxandstepcan express. - Typing the value must remain possible for keyboard and assistive-technology users.
Avoid when
- The user chooses a start and end: use Date range, which pairs two date inputs and offers presets.
- Availability depends on data (booked slots, holidays, per-day capacity): native inputs cannot disable arbitrary dates, so the application must validate and explain, or offer the free slots with Choice group or Select.
- The value is a duration or a relative offset ("3 days"): use Numeric stepper with a unit label.
- The time must carry an explicit time zone: datetime-local has no zone, so state the zone in the label or description or collect it separately with Select.
Behavior to know
- Presentation follows the user's locale and browser; the submitted value does not.
min,maxandstepare native constraints; out-of-range values fail validation on submit.- The input keeps Forma's full-width, 44px-high box; the picker opening is browser chrome and is not styled.
Basic example
The smallest correct markup: the canonical pattern from patterns/date-time-field.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal date and time field
Rendered from the canonical pattern file.
<forma-date-time-field class="forma-component-tag">
<div class="forma-field">
<label class="forma-field__label" for="date-time-field-due">Due date</label>
<span class="forma-field__description" id="date-time-field-due-description">The browser supplies its own date picker; typing the date also works.</span>
<input id="date-time-field-due" name="due" type="date" aria-describedby="date-time-field-due-description">
</div>
</forma-date-time-field>
Click or tap the code once to select all of it, then copy.
Examples
Appointment date and time
Separate date and time inputs for a support call. The date cannot be before today's booking window and the time is limited to 09:00–17:00 in 15-minute steps (step is in seconds).
<forma-date-time-field class="forma-component-tag">
<div class="forma-form-row">
<div class="forma-field">
<label class="forma-field__label" for="date-time-field-appointment-date">Call date</label>
<span class="forma-field__description" id="date-time-field-appointment-date-description">Between 1 October and 31 December 2026.</span>
<input id="date-time-field-appointment-date" name="call-date" type="date" min="2026-10-01" max="2026-12-31" required aria-describedby="date-time-field-appointment-date-description">
</div>
<div class="forma-field">
<label class="forma-field__label" for="date-time-field-appointment-time">Start time (London time)</label>
<span class="forma-field__description" id="date-time-field-appointment-time-description">09:00 to 17:00, on the quarter hour.</span>
<input id="date-time-field-appointment-time" name="call-time" type="time" min="09:00" max="17:00" step="900" required aria-describedby="date-time-field-appointment-time-description">
</div>
</div>
</forma-date-time-field>
Click or tap the code once to select all of it, then copy.
Scheduled maintenance start
A single datetime-local value with a lower bound and an initial value. The time zone is named in the label because datetime-local submits a zone-less local time.
<forma-date-time-field class="forma-component-tag">
<div class="forma-field">
<label class="forma-field__label" for="date-time-field-maintenance-start">Maintenance starts (UTC)</label>
<span class="forma-field__description" id="date-time-field-maintenance-start-description">Customers are notified 48 hours before this time.</span>
<input id="date-time-field-maintenance-start" name="maintenance-start" type="datetime-local" min="2026-10-02T00:00" value="2026-10-04T02:00" aria-describedby="date-time-field-maintenance-start-description">
</div>
</forma-date-time-field>
Click or tap the code once to select all of it, then copy.
Date outside the allowed range
The application rejected a contract end date earlier than the start. aria-invalid and a linked validation message explain the fix; the typed value is kept.
<forma-date-time-field class="forma-component-tag">
<div class="forma-field">
<label class="forma-field__label" for="date-time-field-contract-end">Contract end date</label>
<span class="forma-field__description" id="date-time-field-contract-end-description">Contract starts on 1 November 2026.</span>
<input id="date-time-field-contract-end" name="contract-end" type="date" min="2026-11-01" value="2026-10-15" aria-invalid="true" aria-describedby="date-time-field-contract-end-description date-time-field-contract-end-error">
<p class="forma-validation-message" id="date-time-field-contract-end-error">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Choose a date on or after 1 November 2026.
</p>
</div>
</forma-date-time-field>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile delivery booking
Date and time fields for a delivery at phone width. The grid collapses to one column and the platform picker takes over on tap.
What changes at narrow widths
- The two fields sit side by side when there is room and stack into one column on a phone, because the enclosing grid uses
minmax(min(100%, 16rem), 1fr)tracks. - On touch devices tapping the input opens the platform's full-screen or wheel picker; Forma does not restyle it.
- Inputs keep a 44px minimum height and fill the column, so localized values such as long month names do not overflow.
- Typed entry is still available where the platform supports it; the submitted value is ISO regardless of how the date is displayed.
- Orientation changes only reflow the grid.
<forma-date-time-field class="forma-component-tag">
<div class="forma-form-row">
<div class="forma-field">
<label class="forma-field__label" for="date-time-field-mobile-date">Delivery date</label>
<input id="date-time-field-mobile-date" name="delivery-date" type="date" min="2026-10-01">
</div>
<div class="forma-field">
<label class="forma-field__label" for="date-time-field-mobile-time">Earliest arrival</label>
<span class="forma-field__description" id="date-time-field-mobile-time-description">Hourly slots from 08:00.</span>
<input id="date-time-field-mobile-time" name="delivery-time" type="time" min="08:00" max="18:00" step="3600" aria-describedby="date-time-field-mobile-time-description">
</div>
</div>
</forma-date-time-field>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
type | input | date | time | datetime-local | — | Selects the native control and its value format (YYYY-MM-DD, HH:MM[:SS], YYYY-MM-DDTHH:MM). |
for | label.forma-field__label | id of the input | — | Associates the visible label. |
name | input | string | — | Form field name; the submitted value is always in ISO form. |
value | input | ISO date/time string | empty | Initial value in the machine format for the type, not a localized string. |
min | input | ISO date/time string | — | Earliest allowed value. Pickers typically grey out earlier values; typed earlier values fail validation. |
max | input | ISO date/time string | — | Latest allowed value. |
step | input | seconds (time, datetime-local) or days (date) | 60 for time, 1 for date | Allowed increment; 900 means 15-minute slots. Values off the step fail validation. |
required | input | boolean | absent | Native constraint: the form will not submit while empty. |
aria-describedby | input | id list | — | Links the description (state bounds and time zone there) and any validation message. |
aria-invalid | input | true | absent | Set by the application while a linked validation message is shown. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves focus to the input; in most browsers Tab also moves between the day, month, year, hour and minute segments. |
| ArrowUp / ArrowDown | Increments or decrements the focused segment (native, browser-dependent). |
| Digits | Types directly into the focused segment. |
| Browser picker shortcut | Opening the picker from the keyboard (for example Alt+ArrowDown or Space) varies by browser; typed entry never requires it. |
| Event | Description |
|---|---|
input / change / invalid | Native events. The value is read as an ISO string; Forma adds no events. |
Form behavior
A native input: submits an ISO date, time or local date-time string under name, enforces min, max, step and required, and resets to its initial value on form reset.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Empty | no value | The browser shows its localized placeholder segments (for example dd/mm/yyyy). |
| Filled | value | Displayed in the user's locale. |
| Focus | :focus-visible | Foundation two-tone focus ring around the whole input. |
| Invalid | aria-invalid="true" plus a linked .forma-validation-message | Error text with a non-color mark below the input. Native :invalid from min/max/step is not restyled by Forma. |
| Disabled | disabled attribute | Skipped by focus and not submitted; explain why in the description. |
Accessibility
Forma provides
- Keeps the native input so typed segmented entry, screen reader announcements and the platform picker all remain available.
- Full-width 44px control with the shared focus ring; borders map to CanvasText in forced-colors mode.
Your application supplies
- State the allowed range and, for times, the time zone in visible text; min and max are not announced consistently.
- Explain rejected values in a linked Validation message with the allowed range.
- Do not replace the native input with a custom calendar unless Limen supplies full keyboard grid navigation and typed entry.
- Convert and store time zones in the application; datetime-local carries no zone.
Responsive behavior
- Temporal inputs use a shrinkable border-box with normalized native appearance to avoid iOS intrinsic-width overflow; the native date/time picker remains browser-owned.
- Inputs are
inline-size: 100%of their field, so localized formats and picker icons fit the available width. - No breakpoints of its own; place several fields in Form row so their controls stay level side by side and collapse to one column when narrow.
- Touch devices use their native picker UI, which is full screen or a bottom sheet on most phones.
Motion
- No animation: Forma adds no transition to date and time inputs. Any picker animation is the browser's own.
Usage guidance
Do
- Use min and max for hard limits and repeat them in the description.
- Keep the stored value in ISO form and format for display elsewhere.
Avoid
- Text inputs with a date pattern when a native date input would do.
- Implying a time zone that datetime-local does not store.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.