Docs
Calendar

Calendar

Grid primitive for date selection. Wrapper over react-day-picker (opens in a new tab) v9, dressed with Apollion tokens (colors, spacing, radius, animation).

It is a grid component — it does not handle positioning, popover or trigger. When you need a calendar anchored to an input (the most common case), use InputDate, which wraps the Calendar in a @floating-ui/react popover.

When to use

✅ Use when…🚫 Avoid when…
  • You need inline date selection (no popover) — e.g. dashboard filters, scheduling embedded in a form.
  • You need interval selection (range) with more than one month visible.
  • You want to customize the modal/popover that wraps the calendar — the Calendar is the inner piece.
  • For a date field in a regular form. Use InputDate — it already provides the input, popover, formatting and locale.
  • When you only need month/year (no day). For now the DS does not have a MonthPicker — open an issue in the ROADMAP.

Single

Selection of a single date. Click on days to select; use the header arrows to navigate between months.

Selected: 5/15/2026

maio 2026
const [date, setDate] = useState();
<Calendar mode="single" selected={date} onSelect={setDate} />;

Range

Interval selection, with 2 months visible simultaneously. Click a start date + an end date to define the range.

Select a range

maio 2026
junho 2026
const [range, setRange] = useState();
<Calendar mode="range" selected={range} onSelect={setRange} numberOfMonths={2} />;

Year navigation (caption dropdown)

captionLayout="dropdown" replaces the "May 2026" caption with two dropdowns (month + year). Use it together with startMonth + endMonth to limit the range of available years.

captionLayout="dropdown" enables month + year dropdowns in the header — useful for distant dates.

<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
  captionLayout="dropdown"
  startMonth={new Date(1970, 0, 1)}
  endMonth={new Date(2100, 11, 31)}
/>

Locale

Defaults to ptBR from date-fns/locale. Accepts any other date-fns locale.

import { enUS } from 'date-fns/locale';
<Calendar mode="single" selected={date} onSelect={setDate} locale={enUS} />;

Disabled dates

Accepts the same Matcher syntax as react-day-picker v9 — single Date, range, predicate function, or array.

Weekends and days before 05/15 are disabled.

maio 2026
<Calendar mode="single" selected={date} onSelect={setDate} disabled={[{ before: new Date() }, { dayOfWeek: [0, 6] }]} />

Calendar forwards the react-day-picker props (accessed via vendor). See also the layout props accepted by all components.

See also

ButtonDivider