Design
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 behavior.
This component is fully responsive and designed to be used across mobile, tablet, and desktop without separate variants.
When to use it (and when not to)
Section titled “When to use it (and when not to)”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 using 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.
Quick summary of accessibility & consistency
Section titled “Quick summary of accessibility & consistency”- The Date Picker must meet WCAG 2.1 AA.
- Keyboard interaction must cover the field, trigger, month navigation, and day cells.
- Manual text input is mandatory and cannot be removed.
- Focus must move into the popup when opened and return to the trigger on close.
- Day cells must expose full dates via
aria-label, and selection/disabled state must be programmatically exposed. - This is the approved pattern for collecting specific calendar dates in the system.
Properties
Section titled “Properties”Boolean properties
Section titled “Boolean properties”Required
Data picker
Default: true
Show helper text
Data picker
Default: true
Show icon
Data picker
Default: false
Error variant: true
Show calendar
Data picker
Default: false
Active filled variant: true
State : Status by Filled
Section titled “State : Status by Filled”Rested
Data picker
Filled variants: Empty + Filled
Behavior
Description:
The default interactive state when the field is not being actively edited.
Usage context:
Use for both empty and populated values when no interaction is in progress.
Hover
Data picker
Filled variants: Empty + Filled
Behavior
Description:
Visual change when a pointer is over the field.
Active
Data picker
Filled variants: Empty + Filled
Calendar: Can be opened
Behavior
Description:
The interaction state when users click or press the input.
Usage context:
Calendar assists selection while typed input remains available.
Disabled
Data picker
Filled variants: Empty + Filled
Behavior
Description:
Visible but non-interactive.
Usage context:
Use for read-only or dependency-gated inputs.
Focus
Data picker
Filled variants: Filled
Behavior
Description:
Ready to receive keyboard events without opening the calendar by default.
Usage context:
Highlights the currently edited field for keyboard users.
Error
Data picker
Filled variants: Empty + Filled
Error icon: Required
Behavior
Description:
Validation failure state (typically red) with icon and helper error message.
Usage context:
Triggered after blur when data is invalid.
Styling
Section titled “Styling”Colors
Section titled “Colors”| Name | Applied as | Applied to |
|---|---|---|
color-background-neutral-default | Background color | Date input (unfilled) |
color-background-neutral-default | Background color | Date input (unfilled) |
color-surface-neutral-default | Background color | Date input |
color-surface-neutral-default | Background color | Date input |
color-fill-contrast-default | Background color | Date input (hover) |
color-fill-contrast-default | Background color | Date input (hover) |
color-fill-neutral-muted | Background color | Date input (disabled) |
color-fill-neutral-muted | Background color | Date input (disabled) |
color-border-neutral-default | Border color | Input border, current-day indicator |
color-border-neutral-default | Border color | Input border, current-day indicator |
color-border-neutral-muted | Border color | Date input border |
color-border-neutral-muted | Border color | Date input border |
color-border-focus-neutral-default | Border color | Date input (focus) |
color-border-focus-neutral-default | Border color | Date input (focus) |
color-border-error-default | Border color | Date input (error) |
color-border-error-default | Border color | Date input (error) |
color-border-contrast-default | Divider color | Calendar weekdays separator |
color-border-contrast-default | Divider color | Calendar weekdays separator |
color-foreground-neutral-default | Text color | Input text, day cell |
color-foreground-neutral-default | Text color | Input text, day cell |
color-foreground-neutral-muted | Text color | Disabled day cells |
color-foreground-neutral-muted | Text color | Disabled day cells |
color-foreground-neutral-subtle | Text color | Hover day cells |
color-foreground-neutral-subtle | Text color | Hover day cells |
color-surface-neutral-subtle | Background color | Hover day cells |
color-surface-neutral-subtle | Background color | Hover day cells |
color-surface-contrast-default | Background color | Selected day cell |
color-surface-contrast-default | Background color | Selected day cell |
color-foreground-contrast-default | Text color | Selected day cell |
color-foreground-contrast-default | Text color | Selected day cell |
buttons-main-button-primary-neutral-hover-fill-color | Background color | Selected day cell (hover) |
buttons-main-button-primary-neutral-hover-fill-color | Background color | Selected day cell (hover) |
Spacing
Section titled “Spacing”| Name | Applied as | Applied to |
|---|---|---|
spacing-08 | Cell padding | Weekday labels and day cells |
spacing-08 | Cell padding | Weekday labels and day cells |
radius-xl | Border radius | Calendar day cells |
radius-xl | Border radius | Calendar day cells |
Text Styles
Section titled “Text Styles”| Name | Applied as | Applied to |
|---|---|---|
Lorem Ipsum typography-body-6 | Text style | Input text |
Lorem Ipsum typography-body-6 | Text style | Input text |
Lorem Ipsum typography-body-8 | Text style | Label |
Lorem Ipsum typography-body-8 | Text style | Label |
Lorem Ipsum typography-body-7 (emphasis) | Text style | Selected day cell |
Lorem Ipsum typography-body-7 (emphasis) | Text style | Selected day cell |
Guidance on how to use a component.
- Keep both interaction paths available: typed input and calendar selection.
- Validate on blur and provide a clear error message that includes expected format.
- Use the helper text to communicate a concrete example date format.
- Keep disabled and unavailable dates visible but non-selectable in the calendar.
Guidance on what to avoid when using a component.
- Don’t hide or replace persistent labels with placeholder-only labels.
- Don’t rely on color alone for error or selected state communication.
- Don’t force calendar-only interaction for keyboard and assistive-tech users.
- Don’t trigger validation errors while users are still typing.