Date picker

When to use

• For a date field in a form: a program start date, a session date, a payment due date.
• For a date range in a toolbar or a filter: the period of a check-in or revenue report.

When not to use

• When the calendar is the main content of the view: show a Calendar inline.
• For a date of birth or other dates years away: use the calendar's month and year menus, or three inputs.
• For a time of day: there is no time picker yet; use an Input or a Select of time slots.

Anatomy

A date picker is a composition, as in shadcn's date picker recipe: a Button as the trigger, a Popover, and a Calendar inside it. Open the example to see the popover: the calendar with its month caption, month buttons and day grid, aligned to the trigger's start edge. Picking a day closes the popover and writes the date into the trigger.

Variants

• Single date: the default above. The popover closes on select.
• Range: mode="range" with two months side by side. The popover stays open until the coach clicks outside or presses Escape, so both ends can be picked. The trigger shows "2 Nov – 15 Nov 2026".
• With presets: coach-admin's report filters offer "Last 7 days", "This month" next to the calendar. Put them as buttons above the calendar inside the popover.

States

Day states inside the popover (today, selected, range, disabled) are listed on the Calendar page.

Usage guidelines

• Disable dates that can't be picked, such as past dates for a program start (disabled={{ before: new Date() }}), and say why in help text if it isn't obvious.
• Open the calendar on the month of the current value, or on today when empty.
• Close the popover on select for single dates. Move focus back to the trigger, which Radix does on close.
• Show the error after the popover closes without a date, not while the coach is still choosing.

Content guidelines

• Label: what the date is for: "Program start date", "Report period". Not "Date".
• Placeholder: "Pick a date" or "Pick a date range".
• Value: the Content format: "2 Nov 2026"; ranges "2 Nov – 15 Nov 2026". In Arabic: "2 نوفمبر 2026", with Western digits.
• Help text says what happens on that date: "Week 1 of the program starts on this day."

Accessibility

• The trigger is a button with aria-haspopup="dialog" and aria-expanded, from the Radix popover. It is labelled by both the label and the current value (aria-labelledby lists the two ids), so a screen reader announces "Program start date 2 Nov 2026, button, collapsed". Without that, the label replaces the button text and the date is never read.
• Help and error text are linked with aria-describedby; an invalid trigger has aria-invalid="true".
• autoFocus on the calendar moves focus into the grid when the popover opens.

RTL

• The calendar icon is at the start of the trigger, on the right in RTL. It doesn't mirror.
• The popover aligns to the trigger's start edge (align="start"), its right edge in RTL.
• Inside the popover, the calendar mirrors as described on the Calendar page: weeks run right to left and the month chevrons point outwards.
• Pass locale={lang === "ar" ? ar : enUS} from react-day-picker/locale and numerals="latn", and format the trigger's value with the same locale.

Tokens used

The trigger is an outline Button and the panel a Popover. The calendar inside reads:

Read from components/ui/calendar.tsx at build time, so this list changes when the component does. Opacity modifiers such as /90 are shadcn hover and focus tints on top of the token.

• Layerz-(--z-raised)
• Opacityopacity-(--opacity-disabled)
• Radiusrounded-md rounded-e-md rounded-s-md
• Radiusrounded-none
• Shadowshadow-xs
• Typefont-medium
• Typeleading-none
• Typefont-regular
• Typetext-sm
• Typetext-xs

Props

The date picker has no component of its own. These are the Calendar props; see Popover for the popover parts.

Replaces in coach-admin

Related

Calendar, Popover, Input, Form.