Date Picker

🧭 When to Use a Date Picker

Use a Date Picker when:

• Users need to choose a date with precision and visibility into a calendar

• A date must be picked rather than typed (to ensure consistent formatting)

• You want to provide extra context—like weekends, current date, or disabled days

Avoid Date Pickers when:

• The date input is optional and less likely to be filled

• Speed and simplicity matter more than accuracy (use plain inputs in those cases)

🗓️ Date Picker Items

Date Picker Items make up the interactive calendar grid inside the picker. Each item represents a single day and adjusts visually based on interaction and logic (like current date or disabled range).

🎯 Statuses

• Default – Regular date in the current month

• Current – Today's date; visually highlighted but not automatically selected

• Hover – Mouse over a selectable day

• Focus – Keyboard focus ring applied

• Disabled – Non-interactive days, e.g., dates in the past or future depending on config

• Blank – Placeholder cells for empty start-of-week or end-of-week grid slots

These statuses are auto-calculated and visually reflected using tokens and variants.

🎨 Types

• Default – Standard, unselected date item

• Selected – The currently chosen date; shown with a bold or filled background

Selected types should override all other visual styles except disabled.

🧩 Component Structure

The full Date Picker component is composed of:

1. Input Field

   • Combines Label, Field, and Placeholder or Selected Date

   • Shows the selected value and triggers the calendar on focus or click

2. Calendar Popover

   • A floating container that appears below the input

   • Contains the Date Picker Items, header, and navigation controls (e.g., previous/next month)

3. Date Picker Items

   • Interactive grid of days as described above

   • Auto-aligned by week and localized start day (e.g., Monday or Sunday)

Variants allow switching between full calendar view and smaller inline view.

✏️ Placeholder & Format

You can include placeholder text in the input like “Select a date” via a layer property. Once a date is selected, it replaces the placeholder with a formatted value (e.g., "Apr 3, 2025").

Date format should match the product’s locale or user setting.

♿ Accessibility Considerations

From a design perspective:

• Maintain strong focus states for keyboard navigation across calendar items

• Use icons + visible labels for month navigation

• Clearly indicate disabled days without relying only on color

From a code perspective (if implemented):

• Use role="grid" for the calendar and role="gridcell" for each day

• Use aria-selected="true" on the selected item

• Mark today’s date with aria-current="date"

• The input field should use aria-haspopup="dialog" and aria-expanded for toggling

✅ Best Practices

• Set default or suggested dates when possible

• Disable invalid dates (e.g. past days for booking) to prevent user error

• Always indicate the currently selected day visually

• Add transition effects to calendar changes (e.g. month-to-month) for clarity

• Use tooltips or footers to add context like “Check-in starts at 3pm” if relevant