Select your language
Select other languages

Automatic translation

Loading translator…

Magoomake your components work correctlyBack to homepage

Dates and date ranges

Allows entering a date or date range with manual entry, a calendar, and understandable validation rules.

For working examples and design patterns for this component, see the references tab (opens the references on this page).

COMPONENT GUIDE

Explore behaviors before defining the interface.

Quick guide for designers

When to use

Use for dates or periods. Consider manual entry for known dates and a calendar for exploring availability.

What to design

Show labels, format, start and end, today, selection, unavailability, limits, and errors.

How it behaves

Typing and calendar selection update the same value. Navigating days is not the same as committing a date.

What to document in Figma

Define format, limits, endpoint inclusion, incomplete ranges, focus, commitment, and cancellation.

How to review

Check states and ranges in the design. In the implementation, verify typing, calendar use, and errors on desktop and mobile.

Entry and context

  1. Is the expected format visible and associated with the field? Do start and end have their own labels without relying on position alone?
  2. Does manual entry remain available? Birth dates or dates in the distant past may require excessive navigation if the calendar is the only option.
  3. Do rules distinguish a date without time from an instant with a time zone? Record limits, unavailable days, and whether the final day belongs to the period.

Calendar and range

  1. Can today, the focused day, the selected date, and unavailable days be distinguished without color alone? Are month and year clear?
  2. How do people choose the start and then the end? Design the incomplete range and the rule for a second date earlier than the first without silently swapping field meanings.
  3. Can distant months and years be reached without traversing every day? On small screens, does the calendar fit and retain controls with a virtual keyboard and magnification?

Validation and preservation

  1. Do nonexistent dates, incorrect formats, an end before the start, and unavailability receive specific guidance? Are values preserved for correction?
  2. If availability changes after selection, does the interface explain the issue and allow revising the period without losing other data?

Interaction Methods

Mouse and touch

People can type in the fields or open the calendar through its button. Clicking or tapping a day follows the defined selection and commitment rule.

Keyboard

In native fields, commands follow the platform. In a custom grid calendar, Right and Left arrows move one day; Up and Down arrows move one week; Home and End go to the start and end of the week; Page Up and Page Down change month.

Tab traverses controls and one grid position rather than every day. Enter or Space commits the day according to the adopted model.

If the calendar opens as a modal dialog, keep focus inside while open; Esc closes and returns focus to the trigger without committing a merely focused date. An embedded calendar must not trap focus.

Screen readers

When navigating fields with a screen reader, people identify the label, format, value, and error. In the calendar, navigating days identifies the full date and allows committing selection.

On changing month, people identify the new month and year. With a mobile screen reader, navigation gestures traverse fields and controls; double tapping activates the focused control according to the platform.

Gherkin

BDD (Behavior-Driven Development) methodology focusing on three pillars: User Stories, Acceptance Criteria, and Gherkin Syntax (Given, When, Then).

Scenario: Given that I am on a page containing Dates and date ranges

Educational scenarios for reviewing behavior. Adapt them to context and execute them in the implementation; the presence of this text does not mean tests were performed.

Keyboard navigation

  1. WHEN I use Tab to reach the start and end fields and calendar button
  2. I SEE visible focus and can type dates or open and navigate the calendar according to the documented pattern
  3. THEN, when I commit a date, I SEE the updated value; canceling a modal calendar with Escreturns focus to the trigger without committing the merely focused day

Screen reader on desktop

  1. WHEN I navigate fields and calendar with a desktop screen reader
  2. I HEAR labels, format, and values; in the calendar, I identify the full date, selection, and availability
  3. THEN, when I change month or commit selection, I HEAR or perceive the new context or value; errors are associated with the corresponding field

Screen reader on mobile devices

  1. WHEN I navigate fields with a mobile screen reader
  2. I HEAR which field represents the start and which represents the end and can edit with platform gestures
  3. THEN, when I commit an invalid period, I HEAR or perceive correction guidance and values remain available for editing

Additional scenarios — editorial extension

Type and correct

  1. GIVEN a stated format
  2. WHEN I type a nonexistent date and try to commit it
  3. THEN I receive guidance associated with the field and can correct it without losing the typed value.

Cancel the calendar

  1. GIVEN an open modal calendar
  2. WHEN I navigate days and press Esc
  3. THEN it closes, focus returns to the trigger, and the committed value is not replaced by the merely focused day.

Invalid range

  1. GIVEN start and end
  2. WHEN I enter an end before the start
  3. THEN the interface explains the invalid relationship and preserves the fields for correction according to the documented rule.

Calendar with a screen reader

  1. GIVEN the calendar
  2. WHEN I navigate with a desktop or mobile screen reader
  3. THEN I identify the full date, selection, and availability and can commit or cancel using the platform’s interaction method.

Points to consider

Do not require dragging to select a period. Offer start and end selection without that gesture.

A date without time must not change day through unintended time zone conversion. Verify this rule in storage and display.

The APG calendar example illustrates a model rather than a production-ready implementation. Date ranges require additional decisions.

Implementation notes and behavior decisions

Native fields follow the platform. For a custom grid calendar, document arrow navigation for days and weeks, Home and End for the week, and Page Up and Page Down for months.

Verify each field’s label, format, value, and error. In the calendar, the day name must identify the full date, including month and year.

Communicate month and year when changing views and distinguish focus, selection, and unavailability. Test native pickers on the platforms actually used.

References

Additional references for components of type Dates and date ranges.

Important:
Most references are on the course platform alongside the lessons cited in this material.

Disclaimer:
The links listed here are a curated collection of references where you can find implemented components, rather than recommendations. There is no unified implementation format and no guarantee that these links follow every design pattern. Direct questions to the teams responsible for the linked materials. Before copying a model, remember that all materials are constantly updated and that patterns, particularly proprietary ones, may change.

Technical references and examples consulted for this editorial adaptation. Each source retains its scope; consulting an example does not prove accessibility of another implementation.

W3C APG — Date picker dialog (external link, opens in a new tab)

USWDS — Date range picker (external link, opens in a new tab)

Original content by Marcelo Sales, initially used in the AccessBoost course (external link - opens in a new window). These interactions represent standard industry patterns, but may be customized in specific cases, provided there are sufficient instructions for people to understand the behavioral change.