Accessibility

All picker components ship with built-in accessibility support. Keyboard navigation, ARIA attributes, and focus management work out of the box in every variant — Styled, Tailwind v3/v4, and Headless.

No extra configuration is needed for standard use. This page documents what’s included so you can audit, extend, or replicate the patterns in custom UIs.

Keyboard Navigation

Calendar Pickers

Disabled date skipping: When navigating with arrow keys, disabled dates are automatically skipped. The picker searches up to 365 days in the direction of movement to find the next enabled date.

Auto-month scrolling: When keyboard focus moves to a day in a different month, the calendar view updates to show that month.

Time Picker

Time selection uses a scroll-wheel UI with click/touch interaction. The scroll columns use scroll-snap for precise value selection.

ARIA Attributes

Every interactive element has appropriate ARIA roles and attributes:

Popup & Container

Trigger Button

Calendar Grid

Navigation & Dropdowns

Time Columns

All label strings are customizable through the locale system.

Focus Management

Roving Tabindex

The calendar grid uses the roving tabindex pattern:

• Only the currently focused day cell has tabIndex={0} (tabbable).
• All other day cells have tabIndex={-1} (not tabbable, but focusable via arrow keys).
• This means Tab moves focus out of the calendar grid (to the next control), and arrow keys move focus within the grid.

Popup Focus Trapping

Popup mode uses FloatingFocusManager from @floating-ui/react to:

• Trap focus within the popup while open.
• Return focus to the trigger button when the popup closes.
• Prevent tabbing out of the popup to background content.

Native Elements

Month and year selection use native <select> elements, which are inherently keyboard accessible. Day cells use native <button> elements with appropriate disabled states.

WCAG 2.1 Compliance

The following WCAG 2.1 success criteria are addressed:

Headless: Building Accessible Custom UIs

If you’re using the headless package directly, ensure your custom UI includes:

1. Apply keyboard handler

Pass handleKeyDown to your popup container so arrow key navigation works:

const { handleKeyDown, ... } = useDatePicker({ value, onChange });

<div onKeyDown={handleKeyDown}>
  {/* calendar grid */}
</div>

2. Set correct tabIndex on day cells

Use the isFocused flag from getDayProps():

const dayProps = getDayProps(date);

<button
  role="gridcell"
  tabIndex={dayProps.isFocused ? 0 : -1}
  aria-selected={dayProps.isSelected}
  aria-current={dayProps.isToday ? "date" : undefined}
  aria-label={locale.formatDate(date)}
>
  {dayProps.day}
</button>;

3. Add ARIA roles to your grid

<div role="grid" aria-label={locale.placeholder}>
  <div role="row">
    {locale.weekdays.map((wd) => (
      <div key={wd} role="columnheader">
        {wd}
      </div>
    ))}
  </div>
  {calendar.weeks.map((week, i) => (
    <div key={i} role="row">
      {/* day cells with role="gridcell" */}
    </div>
  ))}
</div>

See Building Custom UI for a complete walkthrough.