Form inputs

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, max and step can 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, max and step are 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.

Canonical

Minimal date and time field

Rendered from the canonical pattern file.

The browser supplies its own date picker; typing the date also works.
HTML · Minimal date and time field Raw HTML for HTML · Minimal date and time field
<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

Scenario

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).

Between 1 October and 31 December 2026.
09:00 to 17:00, on the quarter hour.
HTML · Appointment date and time Raw HTML for HTML · Appointment date and time
<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.

Scenario

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.

Customers are notified 48 hours before this time.
HTML · Scheduled maintenance start Raw HTML for HTML · Scheduled maintenance start
<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.

Scenario

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.

Contract starts on 1 November 2026.

Choose a date on or after 1 November 2026.

HTML · Date outside the allowed range Raw HTML for HTML · Date outside the allowed range
<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 example

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.
HTML · Mobile delivery booking Raw HTML for HTML · Mobile delivery booking
<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.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
typeinputdate | time | datetime-local—Selects the native control and its value format (YYYY-MM-DD, HH:MM[:SS], YYYY-MM-DDTHH:MM).
forlabel.forma-field__labelid of the input—Associates the visible label.
nameinputstring—Form field name; the submitted value is always in ISO form.
valueinputISO date/time stringemptyInitial value in the machine format for the type, not a localized string.
mininputISO date/time string—Earliest allowed value. Pickers typically grey out earlier values; typed earlier values fail validation.
maxinputISO date/time string—Latest allowed value.
stepinputseconds (time, datetime-local) or days (date)60 for time, 1 for dateAllowed increment; 900 means 15-minute slots. Values off the step fail validation.
requiredinputbooleanabsentNative constraint: the form will not submit while empty.
aria-describedbyinputid list—Links the description (state bounds and time zone there) and any validation message.
aria-invalidinputtrueabsentSet by the application while a linked validation message is shown.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves focus to the input; in most browsers Tab also moves between the day, month, year, hour and minute segments.
ArrowUp / ArrowDownIncrements or decrements the focused segment (native, browser-dependent).
DigitsTypes directly into the focused segment.
Browser picker shortcutOpening the picker from the keyboard (for example Alt+ArrowDown or Space) varies by browser; typed entry never requires it.
Events
EventDescription
input / change / invalidNative 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

Date and time field states
StateHow it is expressedPresentation
Emptyno valueThe browser shows its localized placeholder segments (for example dd/mm/yyyy).
FilledvalueDisplayed in the user's locale.
Focus:focus-visibleFoundation two-tone focus ring around the whole input.
Invalidaria-invalid="true" plus a linked .forma-validation-messageError text with a non-color mark below the input. Native :invalid from min/max/step is not restyled by Forma.
Disableddisabled attributeSkipped 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.