Form inputs

Date range

<forma-date-range>

Paired direct date entry with reusable preset affordances and mobile stacking.

Authoring tag
<forma-date-range>
Category
Form inputs
Behavior owner
Native HTML / application
Canonical source
patterns/date-range.html

Purpose

A date range collects a start and an end date as two labelled native input type="date" controls inside a fieldset, optionally followed by preset buttons such as "Last 30 days". Native inputs keep typed entry, the platform picker and min/max validation. Filling the dates from a preset, checking that the end is not before the start, and range preview are application behavior; Forma supplies the layout and its narrow-width stacking.

Use when

  • Users filter or report over a period with a start and an end date.
  • Common periods are worth one-tap shortcuts, while custom dates must stay possible.
  • Typed entry must work for keyboard and assistive-technology users.

Avoid when

Behavior to know

  • From and To are independent native date inputs, each with its own label.
  • Preset buttons are ordinary buttons; they do nothing without application code.
  • Below 40rem the two dates stack and the arrow separator is hidden.

Basic example

The smallest correct markup: the canonical pattern from patterns/date-range.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal date range

Rendered from the canonical pattern file.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Date range
HTML · Minimal date range Raw HTML for HTML · Minimal date range
<forma-date-range class="forma-component-tag">
<fieldset class="forma-date-range">
  <legend>Date range</legend>
  <div class="forma-date-range__fields">
    <label>From <input type="date" name="from"></label>
    <span class="forma-date-range__separator" aria-hidden="true">→</span>
    <label>To <input type="date" name="to"></label>
  </div>
  <div class="forma-date-range__presets" aria-label="Common ranges">
    <button type="button">This month</button>
    <button type="button">Last 30 days</button>
    <button type="button">Year to date</button>
  </div>
</fieldset>
</forma-date-range>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Report period with limits

A billing report limited to the last year of retained data. Both dates are required and bounded with min and max; the description states the limit. Presets are grouped with role=group so their accessible name is exposed.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Billing period

Data is kept for 12 months: 1 October 2025 to 30 September 2026.

HTML · Report period with limits Raw HTML for HTML · Report period with limits
<forma-date-range class="forma-component-tag">
  <fieldset class="forma-date-range" aria-describedby="date-range-bounded-description">
    <legend>Billing period</legend>
    <p class="forma-field__description" id="date-range-bounded-description">Data is kept for 12 months: 1 October 2025 to 30 September 2026.</p>
    <div class="forma-date-range__fields">
      <label>From <input type="date" name="billing-from" min="2025-10-01" max="2026-09-30" value="2026-09-01" required></label>
      <span class="forma-date-range__separator" aria-hidden="true">→</span>
      <label>To <input type="date" name="billing-to" min="2025-10-01" max="2026-09-30" value="2026-09-30" required></label>
    </div>
    <div class="forma-date-range__presets" role="group" aria-label="Billing period presets">
      <button type="button">Last month</button>
      <button type="button">Last quarter</button>
      <button type="button">Last 12 months</button>
    </div>
  </fieldset>
</forma-date-range>

Click or tap the code once to select all of it, then copy.

Scenario

End date before start date

The application found the To date earlier than From. The To input is marked invalid and linked to a validation message that states the fix; both typed dates are kept.

Leave dates

The last day must be on or after 21 December 2026.

HTML · End date before start date Raw HTML for HTML · End date before start date
<forma-date-range class="forma-component-tag">
  <fieldset class="forma-date-range">
    <legend>Leave dates</legend>
    <div class="forma-date-range__fields">
      <label>First day <input type="date" name="leave-from" value="2026-12-21"></label>
      <span class="forma-date-range__separator" aria-hidden="true">→</span>
      <label>Last day <input type="date" name="leave-to" value="2026-12-12" aria-invalid="true" aria-describedby="date-range-end-before-start-error"></label>
    </div>
    <p class="forma-validation-message" id="date-range-end-before-start-error">
      <span class="forma-validation-message__mark" aria-hidden="true">!</span>
      The last day must be on or after 21 December 2026.
    </p>
  </fieldset>
</forma-date-range>

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 activity filter

An activity-log filter at phone width. The dates stack and the presets wrap into rows of full-size buttons.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

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

What changes at narrow widths

  • At 40rem (640px) and below the fields grid becomes one column and the → separator is hidden, so each date input gets the full width.
  • Preset buttons wrap onto as many rows as needed and keep their 44px minimum height.
  • Tapping a date opens the platform picker; typed entry remains available where the platform supports it.
  • In landscape on larger phones the dates may return to side by side if the width exceeds 40rem.
HTML · Mobile activity filter Raw HTML for HTML · Mobile activity filter
<forma-date-range class="forma-component-tag">
  <fieldset class="forma-date-range">
    <legend>Activity between</legend>
    <div class="forma-date-range__fields">
      <label>From <input type="date" name="activity-from" value="2026-09-01"></label>
      <span class="forma-date-range__separator" aria-hidden="true">→</span>
      <label>To <input type="date" name="activity-to" value="2026-09-30"></label>
    </div>
    <div class="forma-date-range__presets" role="group" aria-label="Activity period presets">
      <button type="button">Today</button>
      <button type="button">Last 7 days</button>
      <button type="button">Last 30 days</button>
      <button type="button">This year</button>
    </div>
  </fieldset>
</forma-date-range>

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.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

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
typeinput / buttondate on inputs; button on presets—Native date inputs; presets are type=button so they never submit the form.
nameinputstring—Separate names for the start and end dates; values submit in ISO YYYY-MM-DD form.
valueinputYYYY-MM-DDemptyInitial dates in machine format.
mininputYYYY-MM-DD—Earliest allowed date for that input.
maxinputYYYY-MM-DD—Latest allowed date for that input. Native constraints do not relate From to To.
requiredinputbooleanabsentBlocks submission while that date is empty.
role.forma-date-range__presetsgroup—Gives the preset container a role so its aria-label is exposed.
aria-label.forma-date-range__presetsstring—Names the preset group.
aria-hidden.forma-date-range__separatortrue—The arrow is decorative.
aria-describedbyfieldset / inputid—Links range limits to the fieldset, or an error message to the input that needs correcting.
aria-invalidinputtrueabsentSet by the application on the date that needs correcting.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-date-rangeBlock class—Root fieldset grid (0.5rem gap), full width, margin removed. Its legend gets the compact field-label style.
.forma-date-range__fieldsElement class—Three-column grid (From, separator, To) with bottom alignment; one column at 40rem and below. Labels inside become small grids and date inputs shrink to fit.
.forma-date-range__presetsElement class—Wrapping flex row of preset buttons with a 0.5rem gap.
.forma-date-range__separatorElement class—Decorative arrow between the dates; hidden at 40rem and below.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through From, To and each preset button in source order (and through date segments in most browsers).
ArrowUp / ArrowDownChanges the focused date segment (native, browser-dependent).
Enter / Space on a presetActivates the button; the application fills both dates.
Events
EventDescription
input / change / clickNative events from the date inputs and preset buttons. Forma adds none.

Form behavior

Each date submits separately as an ISO date under its own name and validates its own min, max and required. The fieldset does not enforce that To is on or after From.

States

Date range states
StateHow it is expressedPresentation
Emptyno valuesBoth inputs show the browser's localized placeholder segments.
Filledvalue on both inputsDates display in the user's locale.
Invalidaria-invalid on an input plus a linked .forma-validation-messageError text with a non-color mark below the fields.
Focus:focus-visibleFoundation focus ring on the focused input or preset.

Accessibility

Forma provides

  • A fieldset and legend name the range; each date has its own visible label wrapping the input.
  • Native date inputs keep typed entry, so no picker or drag is required.
  • The separator is hidden from assistive technology, and the layout stacks on narrow screens without reordering.

Your application supplies

  • Give the presets container role="group" (as in these examples) so its aria-label is exposed; the canonical pattern omits the role.
  • Validate the relationship between the dates and explain errors with a Validation message.
  • When a preset fills the dates, announce the new range or make it visible in text; do not move focus unexpectedly.
  • State data retention or other limits in visible text, not only through min and max.

Responsive behavior

  • Above 40rem the two dates share a row with a centered arrow; each date column is minmax(0, 1fr) so localized formats shrink rather than overflow.
  • At 40rem (640px) and below the dates stack and the arrow is hidden.
  • Preset buttons wrap into additional rows at any width.

Motion

  • No animation: the date range has no transitions of its own. Preset buttons use the shared foundation hover and press background interpolation.

Usage guidance

Do

  • Offer presets that match the task (billing months, last 7/30 days) and keep custom dates available.
  • Label the inputs with the domain words ("First day", "Last day") when From/To is ambiguous.

Avoid

  • Replacing typed entry with a calendar-only picker.
  • Silently swapping dates entered in the wrong order.

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.