Components
Calendar
The full calendar, with a toolbar, a view switcher, and day, week, month, year and agenda views.
Calendar puts the pieces together: a CalendarProvider for the state, a toolbar with the title, view switcher, today and previous/next, and the Time Grid, Month View, Year View or 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
pnpm dlx shadcn add @calendarcn/calendarUsage
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:
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 for their data; pass your own events instead.
Build your own
Calendar is a short file. Its toolbar is built from the 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.
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():
| Field | Type |
|---|---|
viewActive view: pick the view component and the period label. | "day" | "week" | "month" | "agenda" | "year" |
monthNameMonth name in the calendar's locale ("October"). Follows the scroll of the week and month views. Empty in year view. | string |
yearFour-digit year ("2026"). | string |
weekNumberWeek number of the displayed week. | number |
goToTodayGoes to the period that contains today. | () => void |
goToPrevGoes back one day, week, month, year or agenda range, by view. | () => void |
goToNextGoes forward one day, week, month, year or agenda range, by view. | () => void |
switchViewSwitches the view and snaps the date to its period. | (view: ViewType) => void |
The live demo is the same idea with more around it: two sidebars, a mini calendar, the Calendar Header and the 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
snapMinutesstep 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.
CalendarProviderrenders 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 areinert. - With reduced motion turned on, scrolling snaps without the slide animation.
Calendar also turns on the single-key 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:
<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:
: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 example colors its text.
API Reference
Calendar takes every CalendarProvider prop (events, view, date, configuration and render slots), plus these:
| Prop | Type | Default |
|---|---|---|
scrollToHourHour the time grid scrolls to when it mounts, e.g. 8.5 for 8:30 AM. | number | 8 |
shortcutsWhether the single-key shortcuts are on. They listen on window, so turn them off when several calendars share a page. | boolean | true |
classNameClass name for the root element. | string | – |
childrenRendered inside the provider, after the calendar. Useful for your own panels that read useCalendar(). | React.ReactNode | – |