Skip to content

Date and time input guidance

Preview Available in release assets

Compose native date and time controls with an explicit time-zone value and server-owned calendar rules.

Date and time input guidance primary example

Show code
<form action="/appointments" method="post" class="thin-stack">
  <fieldset class="thin-fieldset">
    <legend>Appointment time</legend>
    <div class="thin-date-time">
      <div class="thin-field">
        <label for="appointment-date">Date</label>
        <input class="thin-input" id="appointment-date" name="appointment_date" type="date" data-date required aria-describedby="appointment-date-hint" />
        <small class="thin-hint" id="appointment-date-hint">Choose a calendar date. The displayed order follows your browser locale.</small>
      </div>
      <div class="thin-field">
        <label for="appointment-time">Start time</label>
        <input class="thin-input" id="appointment-time" name="appointment_time" type="time" data-time required step="900" aria-describedby="appointment-time-hint" />
        <small class="thin-hint" id="appointment-time-hint">15-minute intervals.</small>
      </div>
      <div class="thin-field">
        <label for="appointment-zone">Time zone</label>
        <select class="thin-select" id="appointment-zone" name="appointment_timezone" required aria-describedby="appointment-zone-hint">
          <option value="">Select a time zone</option>
          <option value="America/Chicago">Central time (America/Chicago)</option>
          <option value="America/New_York">Eastern time (America/New_York)</option>
          <option value="America/Los_Angeles">Pacific time (America/Los_Angeles)</option>
        </select>
        <small class="thin-hint" id="appointment-zone-hint">The server must verify this zone and account for daylight-saving transitions.</small>
      </div>
    </div>
  </fieldset>
  <button class="thin-button" type="submit">Request appointment</button>
</form>

Each authored example uses the production assets and includes copyable markup.

Date only

A native calendar date without application-specific limits.

Show code
<div class="thin-field">
  <label for="travel-date">Travel date</label>
  <input class="thin-input" id="travel-date" name="travel_date" type="date" data-date />
</div>

Time only

A native local time with a meaningful interval.

Show code
<div class="thin-field">
  <label for="reminder-time">Reminder time</label>
  <input class="thin-input" id="reminder-time" name="reminder_time" type="time" data-time step="900" />
</div>

Date, time, and zone

An appointment form submits wall-clock fields and an explicit zone independently.

Show code
<form action="/appointments" method="post" class="thin-stack">
  <fieldset class="thin-fieldset">
    <legend>Appointment time</legend>
    <div class="thin-date-time">
      <div class="thin-field">
        <label for="appointment-date">Date</label>
        <input class="thin-input" id="appointment-date" name="appointment_date" type="date" data-date required aria-describedby="appointment-date-hint" />
        <small class="thin-hint" id="appointment-date-hint">Choose a calendar date. The displayed order follows your browser locale.</small>
      </div>
      <div class="thin-field">
        <label for="appointment-time">Start time</label>
        <input class="thin-input" id="appointment-time" name="appointment_time" type="time" data-time required step="900" aria-describedby="appointment-time-hint" />
        <small class="thin-hint" id="appointment-time-hint">15-minute intervals.</small>
      </div>
      <div class="thin-field">
        <label for="appointment-zone">Time zone</label>
        <select class="thin-select" id="appointment-zone" name="appointment_timezone" required aria-describedby="appointment-zone-hint">
          <option value="">Select a time zone</option>
          <option value="America/Chicago">Central time (America/Chicago)</option>
          <option value="America/New_York">Eastern time (America/New_York)</option>
          <option value="America/Los_Angeles">Pacific time (America/Los_Angeles)</option>
        </select>
        <small class="thin-hint" id="appointment-zone-hint">The server must verify this zone and account for daylight-saving transitions.</small>
      </div>
    </div>
  </fieldset>
  <button class="thin-button" type="submit">Request appointment</button>
</form>

Server validation error

The submitted value remains visible while an application rule is explained.

Show code
<div class="thin-field">
  <label for="closed-date">Appointment date</label>
  <input class="thin-input" id="closed-date" name="appointment_date" type="date" value="2026-12-25" data-date aria-invalid="true" aria-describedby="closed-date-error" />
  <small class="thin-error" id="closed-date-error">Appointments are unavailable on December 25. Choose another date.</small>
</div>

Anatomy

  • Fieldset and legend
  • Native date input
  • Native time input
  • Explicit time-zone control
  • Persistent format or interval guidance

Variants and sizes

  • Date only — shown above
  • Time only — shown above
  • Date and time with explicit zone — shown above
  • Known server-side validation error — shown above

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

  • Empty and required
  • Earliest or latest allowed date
  • Unavailable date returned by the server
  • Ambiguous or skipped daylight-saving time
  • Long localized labels
  • Narrow container

Structured state fixtures are not published for this item yet.

Interaction and keyboard behavior

Typing, picker availability, arrow keys, and displayed formatting remain browser- and locale-owned. The form submits ordinary date, time, and zone strings; the server combines and validates them.

Accessibility

Use visible labels and persistent hints; do not use placeholder text as a format label. Keep controls in logical reading order, and return server errors beside the relevant control with aria-describedby and aria-invalid. Native picker support varies, so never make opening a graphical picker the only path.

Contract
NATIVE
Basis
Native date/time inputs and select; no APG widget
Evidence
  • tests/unit/library/date-time-validation.test.ts

API

Use native input[type=date] and input[type=time] with .thin-input plus data-date or data-time. Submit an IANA time-zone identifier separately whenever an instant or appointment depends on a zone. Author min, max, and step only from real product rules.

Behavior tier: native

Structured host, property, and example tables are not authored for this item yet. Use the summary above and the primary example.

Fallback

Native date, time, and zone controls submit without CSS or JavaScript.

Assets and dependencies

  • /components.css

Dependencies: None

Source: packages/ui/src/items/date-time-guidance/style.ts

Composition

Derived from the examples and style specs, not authored.

Composes