What it is
A calendar control for picking a date, or a start/end range, without asking the reader to type one. It removes the format ambiguity a typed date carries — the reasoning TITAN-INPUT-07 applies to numeric spinners applies here too, to a worse-behaved input. This page covers single-date and range selection together — the design library models both as oneDisplay axis on the same component, not two.
Live example
Exports
Vocabulary
Choose DatePicker when
- The value is a calendar date or a date range.
- The reader benefits from seeing surrounding dates — day of week, proximity to today — to make the choice, rather than recalling one from memory.
Choose something else when
Anatomy
Variants, sizes, and states
Confirmed from the Figma library, not source. Real axes found:
- Mode:
Display=Single Selection/Range Selectionon the picker itself. - Day-cell state:
State=Default/Hover/Pressed/Selected/Disabled/Focused— six states, more than any other Forms component documented so far. - Day-cell role:
Display=Start Date/End Date/Within Range/Default— a range needs to distinguish its two endpoints from the dates between them;Defaultis the single-select case. - Today marker:
Today?=True/False, crossed independently with every state and role above — includingToday?=TrueatState=Selected, confirming today and “selected” are meant to remain visually distinguishable even when they coincide, not for one to silently override the other. - Header navigation:
Navigation=Forward Button/Back Button/None/Back and Forward Buttons.
Edge and failure states
Tokens
Composition
Confirmed directly from the design library’s own composed examples:- Trigger + popover. An
Input Group(the trigger field) paired with aCard(the calendar) — the standard pattern of a field that opens a calendar on interaction. - Inline. The calendar composed directly inside a
Cardwith no trigger field, for an always-visible picker. - Modal. The calendar composed inside a Modal, for a picker that takes over the screen rather than popping over the trigger.
- With buttons. A distinct variant adding a confirm/cancel footer — likely needed for range selection, where a range is provisional until both endpoints are chosen and confirmed, unlike a single date’s instant commit on click.
- Inside Form. A composed example placing this component alongside other fields, confirming it pairs with FieldLabel the same way Input and Select do.
Content
Accessibility
- Each day cell announces its full date and any status that applies — today, selected, or disabled — not a bare number.
- The trigger-plus-popover composition follows the standard disclosure pattern: the trigger reports its expanded state, and focus moves into the calendar on open and returns to the trigger on close.
Constraints
Known issues
DatePicker: open issues
Divergences, open decisions, and undocumented gaps for DatePicker.
Why it works this way
One component for single and range selection keeps the trigger, header, and day-grid mechanics shared, so a reader who has learned to use this component for one date already knows how to use it for a range — the same reasoning behind Input covering single-line and multiline together. Today gets an independent marker from selection so the reader can always locate “today” at a glance, even deep in a different month than whatever is currently selected — losing that anchor would make the calendar harder to reorient in after browsing away from it.Status
Related
- Input — the trigger field’s own chrome and behavior
- FieldLabel — pairs with this component the same way as any other field
- Dates and times — the format rules this component’s display must follow
- Form validation — decides whether a date or range is required or bounded