Date Picker

The calendar view should use button semantics for days, with grid semantics for keyboard navigation and announcements.

Quarantine

A Date Picker is a form input component that lets users enter or select a date. It combines a text field (for direct entry) with a calendar popup (for visual selection), so users can complete the task with either keyboard-first or pointer-first behaviour. The component is fully responsive and designed to be used across mobile, tablet, and desktop without separate variants.

Anatomy

March 2026

Mon

Tue

Wed

Thu

Fri

Sat

Sun

Calendar
Header
Navigation Button
Weekdays
Selected day

When to use it

Use the Date Picker when:

The user needs to select a specific calendar date (for example, a preferred test-drive day).
The date is in the near future or recent past and calendar context improves selection confidence.
Input must be constrained to a valid date range (min/max dates).
Date format consistency is required for downstream processing.

Avoid the Date Picker when:

Only a month or a year is required.
The interaction is relative rather than absolute (for example, “in X days”).
There is no persistent, visible label associated with the field.

Properties

State

Rested, Hover, Active, Disabled, Focus, and Error. Active opens the calendar while keeping typed input available; Focus highlights the currently edited field for keyboard users without opening the popup; Error appears after blur when the value is invalid.

Required

A boolean that marks the field as mandatory. The label reflects the required state visually and through the form submission semantics.

Helper text

Optional text beneath the field — use it to show the expected date format with a concrete example. The component swaps in an error message in the same slot when validation fails.

Calendar icon

A trailing calendar icon doubles as the trigger that opens the popup. It defaults off in the rested state and on in the error variant so the error indicator can take its place.

Calendar popup

The month/year grid that opens on click or tap. Day cells expose full dates via aria-label, disabled or unavailable days remain visible but non-selectable, and the current day carries a distinct outline.

Platform considerations

Desktop

The calendar opens beneath the input. Keyboard interaction covers the field, the trigger, month navigation, and day cells — focus moves into the popup when it opens and returns to the trigger on close.

Tablet

Same behaviour as desktop. Make sure the popup has enough room to render below the input without clipping; flip above when needed.

Mobile

Keep both paths available — typed input shouldn’t disappear in favour of calendar-only on smaller screens. The calendar popup may shift to a sheet pattern but still respects focus and aria-label semantics.

Best practices

Treat the picker as a dual-path control — typing and tapping should both work all the way through.

Do

Keep both interaction paths available (typed input and calendar selection), validate on blur and provide a clear error message that includes the expected format, use helper text to show a concrete example date, and keep disabled and unavailable dates visible but non-selectable inside the calendar.

Don't

Don’t hide or replace the persistent label with placeholder-only text, don’t rely on colour alone for the error or selected state (pair it with an icon or copy), don’t force calendar-only interaction for keyboard and assistive-tech users, and don’t trigger validation errors while users are still typing.

Content guidelines

Make the label specific to the date you’re asking for (“Preferred test-drive date”, not just “Date”). Use the helper text to demonstrate the expected format with a real example (“DD/MM/YYYY — 25/12/2026”) so the user can match the pattern before the picker opens. Error copy should name the rule that failed (“Pick a date after today”) rather than restating the field — pair it with the error icon so the message reads without colour alone.

Styles

The calendar view should use button semantics for days, with grid semantics for keyboard navigation and announcements.

<div class="tng-calendar">
  <div class="tng-calendar-header">
    <button class="tng-icon-button is-ghost">
      <i class="tng-icon icon-chevron-left" aria-hidden="true"></i>
    </button>
    <h2 class="tng-text-body">March 2026</h2>
    <button class="tng-icon-button is-ghost">
      <i class="tng-icon icon-chevron-right" aria-hidden="true"></i>
    </button>
  </div>
  <div class="tng-calendar-weekdays">
    <div>Mon</div>
    <div>Tue</div>
    <div>Wed</div>
    <div>Thu</div>
    <div>Fri</div>
    <div>Sat</div>
    <div>Sun</div>
  </div>
  <div class="tng-calendar-week">
    <button disabled>23</button>
    <button disabled>24</button>
    <button disabled>25</button>
    <button disabled>26</button>
    <button disabled>27</button>
    <button disabled>28</button>
    <button>1</button>
  </div>
  <div class="tng-calendar-week">
    <button>2</button>
    <button>3</button>
    <button>4</button>
    <button>5</button>
    <button>6</button>
    <button>7</button>
    <button>8</button>
  </div>
  <div class="tng-calendar-week">
    <button>9</button>
    <button>10</button>
    <button class="is-selected">11</button>
    <button>12</button>
    <button>13</button>
    <button>14</button>
    <button>15</button>
  </div>
  <div class="tng-calendar-week">
    <button>16</button>
    <button>17</button>
    <button>18</button>
    <button>19</button>
    <button>20</button>
    <button>21</button>
    <button>22</button>
  </div>
  <div class="tng-calendar-week">
    <button>23</button>
    <button>24</button>
    <button>25</button>
    <button class="is-today">26</button>
    <button>27</button>
    <button>28</button>
    <button>29</button>
  </div>
  <div class="tng-calendar-week">
    <button>30</button>
    <button>31</button>
    <button disabled>1</button>
    <button disabled>2</button>
    <button disabled>3</button>
    <button disabled>4</button>
    <button disabled>5</button>
  </div>
</div>

March 2026

Mon

Tue

Wed

Thu

Fri

Sat

Sun

Recipe

Choose a date

DD/MM/YYYY

source code

The date picker follows the WAI-ARIA Date Picker Dialog pattern — a text field paired with a calendar the user opens in a dialog — and meets WCAG 2.1 AA. An accessible date picker keeps typed entry available alongside the calendar, moves and returns focus predictably as the dialog opens and closes, announces the month as it changes, and gives every element an accessible name — so the chosen date is clear whether the user sees it, hears it, or tabs through it.

For designers

Keep the label visible and outside the field in every state, and keep the format hint (for example, DD/MM/YYYY) in helper text at all times — never let the placeholder carry the label or the format.
The field, its text, the helper and error text, the calendar trigger, and every day cell must maintain accessible contrast on every supported surface and in every state. Source: WCAG 1.4.3 Contrast (Minimum).
The selected, today, error, and disabled states must never be conveyed by colour alone — pair each with an icon, a shape, or text. Source: WCAG 1.4.1 Use of Color.
Focus styles must stay visible across the field, trigger, month controls, and day cells, meet contrast requirements on every supported surface, and be clearly distinguishable from hover — including high-contrast mode. Source: WCAG 2.4.7 Focus Visible.
Use semantic colour tokens (e.g. foreground/neutral/default) rather than fixed values, so the component adapts correctly across themes and surfaces.

For developers

The date picker combines a native text field with a Dialog that holds a calendar grid. Typed entry must always stay available — users must be able to complete the task without traversing day-by-day cells. Opening the dialog moves focus into the calendar, focus is trapped inside the dialog while it is open, and closing it (selection, Escape, or outside click) returns focus to the trigger; that traversal is shown in Focus order below and the keys that drive it are in the Keyboard interaction table. Interactive targets must be at least 44 px high for comfortable touch use — comfortably clearing the WCAG AA minimum. Source: WCAG 2.5.8 Target Size (Minimum). The per-element roles, names, and states — the field, trigger, dialog, grid, and day cells — are in the Labelling elements section below.

Keyboard interaction

Key	Action
`Enter` / `Space`	Open the picker from the trigger, or select the focused day
`Arrow keys`	Move focus between days in the grid; `↓` also opens the picker from the field
`Home` / `End`	Move focus to the first / last day of the grid
`Escape`	Close the picker and return focus to the trigger
`Tab` / `Shift + Tab`	Move through the field, trigger, and the controls inside the open picker

Focus order

Focus reaches the field and its trigger; opening the picker moves focus into the dialog, where Tab walks the month controls and the calendar grid, which is a single stop — a roving tabindex moves focus between days while the arrow keys rove within it. Closing the picker returns focus to the trigger. The keys that drive this are in the Keyboard interaction table above.

Choose a date

March 2026

Date field
Calendar trigger
Previous month
Next month
Calendar grid

Source: WCAG 2.4.3 Focus Order.

Labelling elements

Give every element the role, name, and state assistive technology needs.

Date field

A native <input type="text"> associated with its <label> through for/id. Link the format hint and any error text with aria-describedby, and announce error changes with aria-live="polite". Set inputmode="numeric" so mobile surfaces the numeric keyboard.

Trigger

The calendar <button> carries aria-haspopup="dialog", aria-expanded kept in sync with the open state, and aria-controls pointing to the dialog. Give it an accessible name with aria-label (e.g. "Choose date"); its icon is aria-hidden="true".

Dialog

The popup surface takes role="dialog" and is named with aria-label or aria-labelledby. It is non-modal (aria-modal="false") while still trapping and returning focus, so the underlying page stays reachable.

Calendar grid

role="grid" with aria-labelledby pointing to the month/year heading. Weekday labels are role="columnheader" and each week is a role="row", so screen readers announce the day’s column and position.

Month & year heading

The visible <h2> names the grid via aria-labelledby and carries aria-live="polite", so the new month is announced when the user steps between months.

Month navigation buttons

Each icon-only <button> takes its accessible name from aria-label ("Previous month" / "Next month"), with the chevron marked aria-hidden="true".

Day cell

A role="gridcell" wrapper around a native <button>. Expose the full date as the button’s accessible name (aria-label), set aria-selected="true" on the chosen date and aria-current="date" on today, and keep unavailable days as native disabled so they stay visible but out of the tab sequence.

Source: WCAG 4.1.2 Name, Role, Value.