Date Picker

The date picker is built from the Calendar primitive, a react-day-picker calendar styled to the design system. On its own Calendar renders an always-visible month grid; for a compact field that opens a calendar on demand, compose it inside a Popover. Reach for it whenever a user selects a single day, multiple days, or a date range.

Live demo

The interactive story below runs from the deployed Storybook.

Usage

Source: calendar.tsx, popover.tsx

The Calendar primitive on its own:

import { Calendar } from "@beacon/design-system";

const [date, setDate] = React.useState<Date>();

<Calendar mode="single" selected={date} onSelect={setDate} />

The Calendar-in-Popover date-picker pattern: a trigger button shows the chosen date and opens the calendar in a floating panel.

import {
  Button,
  Calendar,
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@beacon/design-system";

const [date, setDate] = React.useState<Date>();

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">
      {date ? date.toLocaleDateString() : "Pick a date"}
    </Button>
  </PopoverTrigger>
  <PopoverContent className="w-auto p-0">
    <Calendar mode="single" selected={date} onSelect={setDate} />
  </PopoverContent>
</Popover>

Parts

Part	Role
Calendar	The month-grid primitive. Drives selection via mode, selected, and onSelect.
CalendarDayButton	The per-day button used internally; exported for advanced day customization.
Popover	Root of the floating-panel pattern that wraps the calendar into a field.
PopoverTrigger	The control (use asChild with a Button) that opens the calendar.
PopoverContent	The floating panel that hosts the Calendar (use className="w-auto p-0" so the grid sets its own width).

Key Calendar props

These come from react-day-picker plus the design-system additions:

Prop	Type	Default	Description
mode	"single" | "multiple" | "range"	—	Selection behavior: one day, many days, or a start-to-end range.
selected	Date | Date[] | DateRange	—	The current selection (shape depends on mode).
onSelect	(value) => void	—	Fires when the selection changes.
showOutsideDays	boolean	true	Show trailing/leading days of adjacent months.
captionLayout	"label" | "dropdown" | ...	"label"	How the month/year caption is rendered.
buttonVariant	Button variant	"ghost"	Variant used for the nav arrows.
disabled	matcher	—	Days to disable (date, range, or predicate).
className / classNames	string / object	—	Styling overrides on the root or named slots.

When to use

• Selecting a single date in a form (a deadline, an appointment) via the Popover pattern.
• Picking a date range (mode="range") for filters or reporting periods.
• Embedding an always-visible month grid (Calendar alone) on a scheduling surface.

Do not force keyboard-heavy users to drag through many months for a far-off date; pair the calendar with a typed-date Input, or enable captionLayout="dropdown" so the month and year can be jumped to directly.