# Calendar

A month grid for picking one date or a range, with keyboard navigation and optional min, max and disabled days.

- Category: Forms
- Page: https://wunderui.com/components/calendar
- Tier: Free

## Install

```bash
npx wunderui-cli add calendar
```

## Import

```tsx
import { Calendar, CalendarDay, CalendarDayProps, CalendarHeader, CalendarHeaderProps, CalendarPeriodCell, CalendarPeriodCellProps, CalendarPeriodPicker, CalendarPeriodPickerProps, CalendarProps } from "@/components/wunderui/calendar"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { Calendar } from "@/components/ui/calendar"

export function Schedule() {
  const [date, setDate] = useState<Date | undefined>(new Date())

  return <Calendar mode="single" size="md" selected={date} onSelect={setDate} />
}
```

Expected result: You see the current month as a six-week grid with today chosen. Click another day to move the choice, and use the arrows or arrow keys to change the month.

## Usage

```tsx
import { useState } from "react"
import { Calendar } from "@/components/ui/calendar"

export function Example() {
  const [date, setDate] = useState<Date | undefined>(new Date(2026, 10, 12))

  return <Calendar mode="single" size="md" selected={date} onSelect={setDate} />
}
```

## When to use

### Use Calendar for

- Showing a month next to a schedule, with a dot on the days that have events
- Picking one day, or a start and an end day, where the calendar is the main control
- A booking window with days that are blocked, booked or still open

### Use something else

- [Date Picker](https://wunderui.com/components/date-picker) for a date in a form field, where the calendar opens in a popover
- [Agenda](https://wunderui.com/components/agenda) for a list of events grouped by day
- [Timeline](https://wunderui.com/components/timeline) for events in the order they happened

## Keyboard

The day grid is one Tab stop with roving focus. Tab enters on the chosen day, today or the first of the month, and the keys below move inside the grid.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the grid once, then on to the next control. The header buttons are separate tab stops before the grid. |
| `ArrowLeft` or `ArrowRight` | Moves focus one day back or forward. At the edge of the month it opens the neighbouring month. |
| `ArrowUp` or `ArrowDown` | Moves focus one week back or forward. |
| `Home` or `End` | Moves focus to the first or the last day of the week. |
| `PageUp` or `PageDown` | Moves focus one month back or forward, keeping the day of the month where it exists. With Shift it moves one year. |
| `Enter` or `Space` | Picks the focused day. A blocked day stays reachable with the arrow keys but is not picked, and nothing is picked while `status` is not `ready`. |
| `Escape` | In the month or year picker: goes back to the days. |

## Behavior

What the calendar does with state, the grid, restrictions and motion.

- **Controlled or not:** You can control the selection and the visible month, or let the calendar keep them. The month starts on the default month, the chosen day or today.
- **Six weeks:** The grid always shows six weeks, Monday first, so the height stays the same in every month. Days of neighbouring months are dimmed but still clickable.
- **Range:** In range mode a click before the start swaps the two ends. While only the start exists, days up to the hovered or focused day show a preview band.
- **Limits:** Days outside the minimum and maximum are blocked and the month arrows lock at the edge. Blocked days are dimmed, announced as unavailable and skipped by Enter, but arrow keys still reach them.
- **Status:** A loading, empty or error status blocks every day, and loading marks the grid as busy. The calendar draws no banner itself.
- **Names:** Each day is named with its full date, such as Thursday, November 12, 2026, plus its marked label or blocked reason. The grid is named by its month heading.
- **Motion:** A day changes its fill quickly on hover and press. Only colour changes and nothing moves.
- **Reduced motion:** With reduced motion nothing changes, since the calendar has no movement. The Tooltip on a blocked day keeps its own motion.

## Anatomy

- `Calendar`: An inline month grid, Monday first, for a single day or a range, with 32 px or 40 px days. For a field with a popover, use DatePicker.
- `CalendarHeader`: The month title between the previous and next buttons, as a plain label or two buttons that open the month and year picker. A hidden arrow keeps its slot, so the title stays centred.
- `Weekday labels`: Seven weekday labels, Mo to Su, each read as the full weekday by screen readers. The grid always shows six weeks, so its height never changes.
- `CalendarDay`: One button per day: selection, today, outside days and unavailable days describe the date, while hover, pressed and focus describe the pointer. The figure marks the start of a range.
- `Range band`: In range mode, days between start and end form one connected tint band with filled, rounded ends. While only the start exists, hovering a later day previews the band.
- `Marked day`: A dot under the number of a day that has data, such as an event or an open slot. The dot is never the only cue: a label is added to the day's accessible name.
- `Today`: Today has a ring on top of any selection. You can override today's date, which helps in demos and tests.
- `CalendarPeriodPicker`: A 3 by 4 grid of months or twelve years with its own previous and next buttons. It opens from the month and year header and also works on its own.
- `Restriction`: A blocked day can show its reason in a tooltip and in its accessible name. A loading, empty or error status blocks every day, and the banner that explains it sits next to the calendar.
- `CalendarPeriodCell`: One month or year button in the period picker.

## Best practices

### Do

- Use Calendar to show a month inline, next to a schedule or in your own popover. To pick a date in a form field, use DatePicker.
- In range mode the first click sets the start, the second the end, and a third starts a new range. A range without an end is a draft, so say in the interface what is missing.
- Use the larger size (40 px days) when the calendar is the main control and the smaller one (32 px) in dense panels.
- Use the month and year header for birth dates and other far dates, so nobody pages month by month. Set the starting month, or control the month when two calendars must move together.
- Limit the choice with a minimum and maximum, and block single days with a list or a rule such as weekends. Say why in a tooltip or in the text nearby.
- Mark days that carry data and name the meaning, for example has events or has open slots.
- While data loads or fails, set the status and show a banner beside the calendar that explains why and offers a retry.

### Don't

- Don't rely on a dot alone to show that a day has events. Name its meaning and list the events next to the calendar.
- Don't show hover, pressed or the range preview as a confirmed choice. A confirmed day never changes on hover, and the preview band is lighter.
- Don't block days without saying why. Screen readers announce a blocked day as unavailable, but a sighted person sees only a dimmed number.

## API reference

### Calendar

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the calendar root. |
| defaultMonth | Date |  | The month to open on when `month` is not set. Defaults to the month of the chosen day, else today. |
| disabled | CalendarDisabled |  | Days inside `min` and `max` that cannot be picked: a list of dates, or a function that returns true for a blocked day. They stay reachable with the arrow keys and are announced as unavailable. |
| disabledReason | string |  | When set, every blocked day shows this text in a tooltip and in its accessible name. |
| header | "label" \| "month-year" | "label" | `label` shows the month as a title; `month-year` shows two buttons that open the month and year picker. |
| hoverDay | Date |  | Shows the range preview up to this day as if it were hovered. For documentation. |
| markedDays | Date[] \| ((date: Date) => boolean) |  | Days that get a dot under the number: a list of dates, or a function that returns true for a marked day. |
| markedLabel | string | "marked" | Words added to the accessible name of a marked day, for example `has events`. Defaults to `marked`. |
| max | Date |  | The latest day that can be picked. Keyboard focus stops here and later months cannot be opened. |
| min | Date |  | The earliest day that can be picked. Keyboard focus stops here and earlier months cannot be opened. |
| mode | "single" | "single" | `single` picks one day and `range` picks a start and an end. It also decides the shape of `selected` and `onSelect`: a `Date`, or `{ from, to }`. |
| month | Date |  | The visible month, to control it. Use it with `onMonthChange` when two calendars must move together. |
| navigation | "both" \| "previous" \| "next" \| "none" | "both" | Which arrows to show: `both` (the default), `previous`, `next` or `none`. A hidden arrow keeps its slot. |
| onMonthChange | (month: Date) => void |  | Called with the first day of the new month when the arrows, the keyboard or the period picker change it. |
| onSelect | (date: Date) => void |  | Called with the day that was picked, or in `range` mode with the new `{ from, to }`. A range without `to` is a draft. |
| reasonDefaultOpenDay | Date |  | The blocked day whose `disabledReason` tooltip starts open. For documentation. |
| selected | Date |  | The chosen day (`single`) or range (`range`). The calendar does not keep it: update it in `onSelect`. |
| size | "sm" \| "md" | "sm" | The size of the day cells: `sm` is 32 px (the default) and `md` is 40 px. |
| status | "ready" \| "loading" \| "empty" \| "error" | "ready" | The state of the data behind the calendar: `ready` (the default), `loading`, `empty` or `error`. Anything but `ready` blocks every day. |
| today | Date |  | Overrides the date of today, which defaults to `new Date()`. Use it for demos and tests. |

### CalendarDay

| Prop | Type | Default | Description |
|---|---|---|---|
| interaction | "rest" \| "hover" \| "pressed" \| "focus" | "rest" | Forces the look of a pointer state (`rest`, `hover`, `pressed`, `focus`) for documentation. Real hover, press and focus need no prop. |
| marked | boolean |  | Draws a dot under the number. |
| outside | boolean |  | Dims the day because it belongs to the neighbouring month. |
| selection | "none" \| "single" \| "start" \| "middle" \| "end" \| "preview" | "none" | What the day means in the choice: `none`, `single`, `start`, `middle`, `end` or `preview` (the lighter band while a range is being chosen). |
| size | "sm" \| "md" | "md" | The size of the cell: `sm` is 32 px and `md` is 40 px. |
| today | boolean |  | Rings the day as today, on top of any selection. |
| unavailable | boolean |  | Dims the day and blocks the pointer. Set it for days outside `min` and `max`, blocked days and every day while the data is not ready. |

Also accepts React.ButtonHTMLAttributes attributes.

### CalendarHeader

| Prop | Type | Default | Description |
|---|---|---|---|
| month* | Date |  | The month the title shows. |
| className | string |  | Extra classes for the header row. |
| headingId | string |  | The id of the title, so the grid can name itself by it. |
| navigation | "both" \| "previous" \| "next" \| "none" | "both" | Which arrows to show: `both`, `previous`, `next` or `none`. |
| nextDisabled | boolean |  | Disables the next button, for example at the maximum date. |
| onMonthClick | () => void |  | Called when the month button of the `month-year` header is pressed. |
| onNext | () => void |  | Called when the next button is pressed. |
| onPrevious | () => void |  | Called when the previous button is pressed. |
| onYearClick | () => void |  | Called when the year button of the `month-year` header is pressed. |
| previousDisabled | boolean |  | Disables the previous button, for example at the minimum date. |
| size | "sm" \| "md" | "sm" | `sm` or `md`, to match the size of the days. |
| type | "label" \| "month-year" | "label" | `label` for a title, `month-year` for two buttons. |

### CalendarPeriodCell

| Prop | Type | Default | Description |
|---|---|---|---|
| current | boolean |  | Rings the cell as the current month or year. |
| interaction | "rest" \| "hover" \| "pressed" \| "focus" | "rest" | Forces the look of a pointer state for documentation. |
| selected | boolean |  | Fills the cell as the chosen month or year. |
| unavailable | boolean |  | Dims the cell and blocks the pointer. |

Also accepts React.ButtonHTMLAttributes attributes.

### CalendarPeriodPicker

| Prop | Type | Default | Description |
|---|---|---|---|
| type* | "month" \| "year" |  | `month` shows the twelve months of a year, `year` shows twelve years. |
| className | string |  | Extra classes for the picker root. |
| max | Date |  | Months or years after this are unavailable. |
| min | Date |  | Months or years before this are unavailable. |
| month | Date |  | The reference month: its year is shown, or the window of twelve years that contains it. |
| onNavigate | (reference: Date) => void |  | Called with the new reference date when the previous or next button moves to another year or window. |
| onSelect | (date: Date) => void |  | Called with the first day of the chosen month, or with a date in the chosen year. |
| selected | Date |  | The chosen month or year, filled in the grid. |
| today | Date |  | Overrides the date of today, which gets the ring. |

## Examples

### Header: a title with arrows, or month and year buttons

```tsx
import { useState } from "react"
import { Calendar } from "@/components/ui/calendar"

export function Example() {
  const [date, setDate] = useState<Date | undefined>(new Date(2026, 10, 12))

  return (
    <Calendar
      mode="single"
      size="md"
      selected={date}
      onSelect={setDate}
    />
  )
}
```

### Period picker: a grid of months or of years

```tsx
import { useState } from "react"
import { CalendarPeriodPicker } from "@/components/ui/calendar"

export function Example() {
  const [month, setMonth] = useState<Date | undefined>(new Date(2026, 10, 1))

  return <CalendarPeriodPicker type="month" selected={month} onSelect={setMonth} />
}
```

### Day: selection, today, a dot, outside the month and unavailable

```tsx
import { CalendarDay } from "@/components/ui/calendar"

export function Example() {
  return (
    <div className="flex">
      <CalendarDay size="md">11</CalendarDay>
      <CalendarDay size="md">12</CalendarDay>
      <CalendarDay size="md" selection="single">13</CalendarDay>
      <CalendarDay size="md">14</CalendarDay>
      <CalendarDay size="md">15</CalendarDay>
    </div>
  )
}
```

### Marks and limits: dots, min and max, and the reason for a blocked day

```tsx
import { useState } from "react"
import { Calendar } from "@/components/ui/calendar"

export function Example() {
  const [date, setDate] = useState<Date | undefined>(new Date(2026, 10, 12))

  return (
    <Calendar
      mode="single"
      size="md"
      markedDays={[new Date(2026, 10, 10), new Date(2026, 10, 12), new Date(2026, 10, 13), new Date(2026, 10, 17), new Date(2026, 10, 19)]}
      markedLabel="has events"
      selected={date}
      onSelect={setDate}
    />
  )
}
```

### Status: ready, loading, empty and error

```tsx
import { useState } from "react"
import { Calendar } from "@/components/ui/calendar"

export function Example() {
  const [date, setDate] = useState<Date | undefined>()

  return <Calendar mode="single" size="md" status="ready" selected={date} onSelect={setDate} />
}
```

## In context

### Schedule sidebar: dots on the days with events

The calendar is the control, with no popover or field. Dots mark days with events, and the agenda below lists the events of the chosen day.

```tsx
import { useState } from "react"
import { Calendar } from "@/components/ui/calendar"

const EVENTS: Record<number, { time: string; title: string }[]> = {
  10: [{ time: "10:00", title: "Design review" }],
  12: [
    { time: "09:30", title: "Sprint planning" },
    { time: "14:00", title: "Release check" },
  ],
  13: [{ time: "11:00", title: "Customer call with Priya Raman" }],
  17: [{ time: "10:30", title: "Roadmap sync" }],
  19: [{ time: "15:00", title: "Launch rehearsal" }],
  24: [{ time: "13:00", title: "Quarterly review" }],
}

export function Example() {
  const [day, setDay] = useState<Date | undefined>(new Date(2026, 10, 12))
  const events = day ? (EVENTS[day.getDate()] ?? []) : []

  return (
    <div className="flex w-fit flex-col gap-4 rounded-xl border border-border bg-card p-4">
      <Calendar
        mode="single"
        size="md"
        selected={day}
        onSelect={setDay}
        markedDays={(date) => date.getMonth() === 10 && date.getDate() in EVENTS}
        markedLabel="has events"
      />
      <div className="flex flex-col gap-2 border-t border-border pt-4">
        <p className="text-sm font-medium text-foreground">
          {day?.toLocaleDateString("en-US", { weekday: "long", month: "long", day: "numeric" })}
        </p>
        {events.length === 0 && <p className="text-sm text-text-secondary">No events</p>}
        {events.map((event) => (
          <p key={event.title} className="flex gap-3 text-sm text-text-secondary">
            <span className="w-12 tabular-nums text-text-tertiary">{event.time}</span>
            {event.title}
          </p>
        ))}
      </div>
    </div>
  )
}
```

### Booking window: weekdays in the next three weeks

Weekends, one booked day and every day outside the window are blocked, and a dot marks days with open slots. Book a demo stays off until a day is chosen.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Calendar } from "@/components/ui/calendar"

const isWeekend = (day: Date) => day.getDay() === 0 || day.getDay() === 6
const isBooked = (day: Date) => day.getDate() === 18
const FIRST = new Date(2026, 10, 9)
const LAST = new Date(2026, 10, 27)
const hasSlots = (day: Date) => day >= FIRST && day <= LAST && !isWeekend(day) && !isBooked(day)

export function Example() {
  const [day, setDay] = useState<Date | undefined>()

  return (
    <div className="flex w-fit flex-col gap-4 rounded-xl border border-border bg-card p-4">
      <Calendar
        mode="single"
        size="md"
        selected={day}
        onSelect={setDay}
        min={FIRST}
        max={LAST}
        disabled={(date) => isWeekend(date) || isBooked(date)}
        disabledReason="No slots on this day"
        markedDays={hasSlots}
        markedLabel="has open slots"
      />
      <div className="flex items-center gap-3 border-t border-border pt-4">
        <p className="flex-1 text-sm text-text-secondary">
          {day ? day.toLocaleDateString("en-US", { weekday: "long", month: "long", day: "numeric" }) : "Pick a day"}
        </p>
        <Button variant="gradient" size="sm" disabled={!day}>
          Book a demo
        </Button>
      </div>
    </div>
  )
}
```

### Trip dates: a range with the number of nights

The first click sets the check-in day and the second the check-out day. The line below says what is missing, then counts the nights, and Clear starts again.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Calendar } from "@/components/ui/calendar"

const short = (day: Date) => day.toLocaleDateString("en-US", { month: "short", day: "numeric" })

export function Example() {
  const [range, setRange] = useState<{ from?: Date; to?: Date }>({
    from: new Date(2026, 10, 20),
    to: new Date(2026, 10, 24),
  })
  const nights = range.from && range.to ? Math.round((range.to.getTime() - range.from.getTime()) / 86_400_000) : 0

  return (
    <div className="flex w-fit flex-col gap-4 rounded-xl border border-border bg-card p-4">
      <Calendar mode="range" size="md" selected={range} onSelect={setRange} min={new Date(2026, 10, 9)} />
      <div className="flex items-center gap-3 border-t border-border pt-4">
        <p className="flex-1 text-sm text-text-secondary">
          {range.from && range.to
            ? `${short(range.from)} – ${short(range.to)} · ${nights} nights`
            : range.from
              ? "Select a check-out date"
              : "Select a check-in date"}
        </p>
        <Button variant="plain" size="sm" disabled={!range.from} onClick={() => setRange({})}>
          Clear
        </Button>
      </div>
    </div>
  )
}
```

## For AI agents

`get_component("calendar")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
