# Calendar

The full calendar, with a toolbar, a view switcher, and day, week, month, year and agenda views.

Live example, interactive at https://calendarcn.xyz/docs/components/calendar. Its source:

```tsx title="src/examples/calendar-demo.tsx"
"use client";

import * as React from "react";

import { Calendar } from "@/components/calendar";
import { createSampleEvents } from "@/lib/sample-events";

export function CalendarDemo() {
  // The provider reads its initial events once, so create them once
  const [initialEvents] = React.useState(() => createSampleEvents(new Date()));

  return <Calendar defaultEvents={initialEvents} />;
}
```

`Calendar` puts the pieces together: a [`CalendarProvider`](/docs/components/calendar-core) for the state, a toolbar with the title, view switcher, today and previous/next, and the [Time Grid](/docs/components/time-grid), [Month View](/docs/components/month-view), [Year View](/docs/components/year-view) or [Agenda View](/docs/components/agenda-view) below it. It takes every `CalendarProvider` prop, and the CLI copies its source into your project, so change the toolbar or the layout right in `components/calendar.tsx`.

## Installation

```bash
npx shadcn add @calendarcn/calendar
```

Or install it by hand:

1. Install the items it builds on: `@calendarcn/calendar-header`, `@calendarcn/time-grid`, `@calendarcn/month-view`, `@calendarcn/agenda-view`, `@calendarcn/year-view`
2. Copy these files into your project, keeping the paths under your components, hooks and lib folders:
   - [`components/calendar.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/calendar.tsx)

## Usage

```tsx
import { Calendar } from "@/components/calendar";

export function Schedule() {
  return (
    // The calendar fills its parent's height
    <div className="h-[600px]">
      <Calendar defaultEvents={events} />
    </div>
  );
}
```

Events, the view and the date can each be left to the calendar (`defaultEvents`, `defaultView`, `defaultDate`) or controlled (`events` with `onEventsChange`, and so on), the same as on [`CalendarProvider`](/docs/components/calendar-core#calendarprovider):

```tsx
const [events, setEvents] = React.useState(initialEvents);

<Calendar events={events} onEventsChange={setEvents} defaultView="month" />;
```

The view switcher offers day, week, month, year and agenda, 2 to 9 days at a time, and the weekend, declined events and week number settings. The examples use `createSampleEvents()` from [Sample Data](/docs/sample-data) for their data; pass your own events instead.

## Build your own

`Calendar` is a short file. Its toolbar is built from the [Calendar Header](/docs/components/calendar-header)'s parts, and that item's `CalendarHeader` is the live demo's fuller header, with panel toggles. For a header of your own, compose the parts yourself: the provider owns the state, your header reads it with `useCalendar()`, and the body renders whichever view the provider is on.

```tsx
import { AgendaView } from "@/components/agenda-view";
import { CalendarProvider, useCalendar } from "@/components/calendar-provider";
import { MonthView } from "@/components/month-view";
import { WeekView } from "@/components/week-view";
import { YearView } from "@/components/year-view";

export function MyCalendar() {
  return (
    <CalendarProvider defaultEvents={events}>
      <div className="flex h-[600px] flex-col">
        <Header />
        <div className="min-h-0 flex-1">
          <Body />
        </div>
      </div>
    </CalendarProvider>
  );
}

function Header() {
  const { monthName, year, goToToday, goToPrev, goToNext, switchView } =
    useCalendar();
  // Title, today, previous/next and a view switcher
}

function Body() {
  const { view } = useCalendar();
  if (view === "month") return <MonthView />;
  if (view === "agenda") return <AgendaView />;
  if (view === "year") return <YearView />;
  return <WeekView />;
}
```

A header like this needs these fields of [`useCalendar()`](/docs/components/calendar-core#usecalendar):

| Field | Type | Description |
| --- | --- | --- |
| `view` | `"day" \| "week" \| "month" \| "agenda" \| "year"` | Active view: pick the view component and the period label. |
| `monthName` | `string` | Month name in the calendar's locale ("October"). Follows the scroll of the week and month views. Empty in year view. |
| `year` | `string` | Four-digit year ("2026"). |
| `weekNumber` | `number` | Week number of the displayed week. |
| `goToToday` | `() => void` | Goes to the period that contains today. |
| `goToPrev` | `() => void` | Goes back one day, week, month, year or agenda range, by view. |
| `goToNext` | `() => void` | Goes forward one day, week, month, year or agenda range, by view. |
| `switchView` | `(view: ViewType) => void` | Switches the view and snaps the date to its period. |

The [live demo](/) is the same idea with more around it: two sidebars, a mini calendar, the [Calendar Header](/docs/components/calendar-header) and the [Command Menu](/docs/components/command-menu).

## Keyboard & accessibility

Every event is a button you can reach with `Tab`. The views only handle keys while one of their events has focus, so a calendar embedded in your page never takes over the page's own shortcuts.

| Action                           | Keys                                                        |
| -------------------------------- | ----------------------------------------------------------- |
| Next or previous event on screen | `Tab` / `⇧+Tab`                                                   |
| Open the event's details         | `Enter` or `Space`                                                  |
| Close the details                | `Esc` outside a field or menu. Focus goes back to the event. |
| Move a day earlier or later      | `Alt+←` / `Alt+→`                                                 |
| Move earlier or later            | `Alt+↑` / `Alt+↓`                                                 |
| Make it end earlier or later     | `Alt+⇧+↑` / `Alt+⇧+↓`                                                 |

- In a field or menu of the details, `Esc` only closes it and restores the value from before. Press it again to close the details.
- In the day and week views and the agenda, `Alt` + `↑` / `↓` move a timed event by one `snapMinutes` step and keep it inside the visible hours. In month view they move it a week.
- Moving an event past the visible days moves the view with it, and focus follows the event.
- `CalendarProvider` renders a polite live region (`role="status"`) that announces each move, resize and create, each delete, cut, copy, duplicate and paste, and each undo and redo, e.g. "Moved Team standup to Tuesday, October 27, 9:15 AM".
- Each event is labelled with its title and time and reports its selection with `aria-pressed`. Day columns, month cells and agenda days are labelled groups with the full date. Year view's months are grids named by month and year, and each day is a button named by its date and its number of events. Decorative parts (time axis, grid lines, drag previews) are hidden from assistive tech, and off-screen scroll buffers are `inert`.
- With reduced motion turned on, scrolling snaps without the slide animation.

`Calendar` also turns on the single-key [keyboard shortcuts](/docs/keyboard-shortcuts) (`T`, `J`/`K`, `D`, `W`, `M`, `Y`, `A`…). They listen on the whole page, so pass `shortcuts={false}` when several calendars share a page or the keys clash with your app's.

## In a dialog

The calendar works inside a shadcn/ui Dialog or Sheet. The event details then render inside the dialog rather than at the end of the page, so the dialog's focus trap and outside presses leave them alone. A dialog that clips or scrolls its content (`overflow-hidden`, `overflow-auto`) can clip the details too.

Pressing `Esc` closes the details first. A Radix dialog stays open. A Base UI dialog closes as well, unless you keep it open on an `Esc` the details already handled:

```tsx
<Dialog
  onOpenChange={(open, { reason, event, cancel }) => {
    if (!open && reason === "escape-key" && event.defaultPrevented) cancel();
  }}
>
```

## Theming

The calendar uses your shadcn/ui theme (`--background`, `--foreground`, `--border`, `--muted-foreground`, `--popover`) plus a few tokens of its own, which the CLI adds to your CSS file for light mode (`:root`) and dark mode (`.dark`). Today's date and the current-time line use `--primary`.

| Variable                 | Used for                                                      |
| ------------------------ | ------------------------------------------------------------- |
| `--event-{color}`        | Event text: the title and time of the default content         |
| `--event-{color}-bg`     | Event background                                              |
| `--event-{color}-border` | The bar on an event's left edge, and the color swatches       |
| `--calendar-weekend`     | Background of weekend columns and weekend cells in month view |

`{color}` is one of `red`, `orange`, `yellow`, `green`, `blue`, `purple` and `gray`. Override them to restyle every event of that color:

```css
:root {
  --event-blue: #1d4ed8;
  --event-blue-bg: #dbeafe;
  --event-blue-border: #3b82f6;
}

.dark {
  --event-blue: #93c5fd;
  --event-blue-bg: #1e3a8a;
  --event-blue-border: #3b82f6;
}
```

They're also Tailwind colors (`text-event-blue`, `bg-event-blue-bg`, `bg-event-blue-border`), which is how the [custom content](/docs/components/calendar-core#custom-event-content) example colors its text.

## API Reference

`Calendar` takes every [`CalendarProvider` prop](/docs/components/calendar-core#calendarprovider) (events, view, date, configuration and render slots), plus these:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scrollToHour` | `number` | `8` | Hour the time grid scrolls to when it mounts, e.g. `8.5` for 8:30 AM. |
| `shortcuts` | `boolean` | `true` | Whether the single-key shortcuts are on. They listen on `window`, so turn them off when several calendars share a page. |
| `className` | `string` | – | Class name for the root element. |
| `children` | `React.ReactNode` | – | Rendered inside the provider, after the calendar. Useful for your own panels that read `useCalendar()`. |
