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
- Only one date is needed: use Date and time field.
- The range is numeric rather than calendar dates: use Range entry.
- The period must include times of day: use two Date and time field inputs with type=datetime-local and a stated time zone.
- The user picks from a few fixed periods only: use Segmented control or Choice group.
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.
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.
<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
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.
<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.
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.
<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 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.
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.
<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.
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.
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 / button | date on inputs; button on presets | — | Native date inputs; presets are type=button so they never submit the form. |
name | input | string | — | Separate names for the start and end dates; values submit in ISO YYYY-MM-DD form. |
value | input | YYYY-MM-DD | empty | Initial dates in machine format. |
min | input | YYYY-MM-DD | — | Earliest allowed date for that input. |
max | input | YYYY-MM-DD | — | Latest allowed date for that input. Native constraints do not relate From to To. |
required | input | boolean | absent | Blocks submission while that date is empty. |
role | .forma-date-range__presets | group | — | Gives the preset container a role so its aria-label is exposed. |
aria-label | .forma-date-range__presets | string | — | Names the preset group. |
aria-hidden | .forma-date-range__separator | true | — | The arrow is decorative. |
aria-describedby | fieldset / input | id | — | Links range limits to the fieldset, or an error message to the input that needs correcting. |
aria-invalid | input | true | absent | Set by the application on the date that needs correcting. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-date-range | Block class | — | Root fieldset grid (0.5rem gap), full width, margin removed. Its legend gets the compact field-label style. |
.forma-date-range__fields | Element 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__presets | Element class | — | Wrapping flex row of preset buttons with a 0.5rem gap. |
.forma-date-range__separator | Element class | — | Decorative arrow between the dates; hidden at 40rem and below. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves through From, To and each preset button in source order (and through date segments in most browsers). |
| ArrowUp / ArrowDown | Changes the focused date segment (native, browser-dependent). |
| Enter / Space on a preset | Activates the button; the application fills both dates. |
| Event | Description |
|---|---|
input / change / click | Native 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
| State | How it is expressed | Presentation |
|---|---|---|
| Empty | no values | Both inputs show the browser's localized placeholder segments. |
| Filled | value on both inputs | Dates display in the user's locale. |
| Invalid | aria-invalid on an input plus a linked .forma-validation-message | Error text with a non-color mark below the fields. |
| Focus | :focus-visible | Foundation 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.