---
title: "Calendar"
description: "Month grid for picking a single date, multiple dates, or a range."
links:
  doc: https://cladd.io/react/components/calendar/
  api: https://cladd.io/react/components/calendar/#api-reference
---

# Calendar

An inline month grid for picking dates. Use it for date fields, scheduling
panels, and booking flows where the calendar stays on screen. For a compact
trigger that opens the grid in a popover, reach for
[`DatePicker`](/react/components/date-picker/) instead.

```tsx
<Calendar mode="single" selected={selected} onSelect={setSelected} />
```

## Usage

`Calendar` is built on [`react-day-picker`](https://daypicker.dev/), which cladd treats as an optional peer dependency and does **not** install for you — add it explicitly:

```bash
npm install react-day-picker
```

`Calendar` then ships from a subpath, not the main barrel:

```tsx
import { Calendar } from '@cladd-ui/react/calendar';

function Example() {
  const [selected, setSelected] = useState();

  return <Calendar mode="single" selected={selected} onSelect={setSelected} />;
}
```

## Examples

### Sizes

The grid and its controls follow the `sm` → `2xl` size scale. The default is
`md`. Tune the navigation buttons separately with `controlSize`, which takes a
[`Button`](/react/components/button/) size.

```tsx
<Calendar
  size={size}
  mode="single"
  selected={selected}
  onSelect={setSelected}
/>
```

### Colors

Use the `color` prop to tint the selected day and focus ring with any accent.

```tsx
<Calendar
  color={color}
  mode="single"
  selected={selected}
  onSelect={setSelected}
/>
```

### Range

Set `mode="range"` to select a start and end date. Pair it with
`numberOfMonths` to show several months at once — handy for picking spans that
cross a month boundary. The selection is a `DateRange` (`{ from, to }`).

```tsx
<Calendar
  mode="range"
  numberOfMonths={2}
  selected={range}
  onSelect={setRange}
/>
```

### Multiple

Set `mode="multiple"` to collect any number of individual dates. The selection
is a `Date[]`.

```tsx
<Calendar mode="multiple" selected={days} onSelect={setDays} />
```

### Dropdown navigation

Set `captionLayout="dropdown"` to swap the month and year labels for select
menus, so users can jump across the calendar without clicking through every
month.

```tsx
<Calendar
  mode="single"
  captionLayout="dropdown"
  selected={selected}
  onSelect={setSelected}
/>
```

### Header and footer

Pass `header` and `footer` to render your own content above and below the grid.
Here the footer echoes the current selection as a
[`Chip`](/react/components/chip/) and the header uses a
[`SectionTitle`](/react/components/section-title/).

```tsx
<Calendar
  mode="single"
  color="brand"
  selected={selected}
  onSelect={setSelected}
  header={<SectionTitle>Pick a date</SectionTitle>}
  footer={
    selected ? (
      <Chip color="brand">
        {selected.toLocaleDateString(undefined, {
          month: 'short',
          day: 'numeric',
          year: 'numeric',
        })}
      </Chip>
    ) : (
      <span className="text-cladd-fg-softer">No date selected</span>
    )
  }
/>
```

### Playground

```tsx
{mode === 'range' ? (
  <Calendar
    size={size}
    color={color}
    mode="range"
    numberOfMonths={2}
    selected={range}
    onSelect={setRange}
  />
) : mode === 'multiple' ? (
  <Calendar
    size={size}
    color={color}
    mode="multiple"
    selected={days}
    onSelect={setDays}
  />
) : (
  <Calendar
    size={size}
    color={color}
    mode="single"
    selected={single}
    onSelect={setSingle}
  />
)}
```

## API Reference

`Calendar` is built on
[react-day-picker](https://daypicker.dev/) and forwards every `DayPicker` prop
straight through, so the full day-picker API is available alongside the cladd
props below. That includes `mode` (`'single' | 'multiple' | 'range'`),
`selected`, `onSelect`, `numberOfMonths`, `captionLayout`
(`'label' | 'dropdown'`), `disabled`, and `startMonth` / `endMonth`. `size` is a
`CalendarSize` (`'sm' | 'md' | 'lg' | 'xl' | '2xl'`).

**Inherits from:** [`DayPicker`](/react/components/day-picker/)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color?` | `Color` | — | Accent color token. Sets the `cladd-color-{name}` class - drives selected fill, today, and focus ring. Default: theme accent. |
| `controlSize?` | `ButtonSize` | `'sm'` | Size of the nav buttons and caption dropdowns. Default `'sm'`. |
| `footerClassName?` | `string` | — | Extra classes for the `footer` element. |
| `header?` | `ReactNode` | — | Custom content rendered above the calendar grid, inside the calendar container (mirrors `footer`). |
| `headerClassName?` | `string` | — | Extra classes for the `header` wrapper. |
| `size?` | `CalendarSize` | `'md'` | Sizing token. Drives day-cell size and font sizes. Default `'md'`. |