# Calendar Sidebar

The left sidebar of the demo, with the mini calendar, scheduling, "Meet with..." and the calendar list.

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

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

import * as React from "react";
import { ChevronLeftIcon, ChevronRightIcon, PanelLeftIcon } from "lucide-react";

import { CalendarProvider, useCalendar } from "@/components/calendar-provider";
import { CalendarSidebar } from "@/components/calendar-sidebar";
import type { CalendarInfo } from "@/components/calendar-types";
import { WeekView } from "@/components/week-view";
import { Button } from "@/components/ui/button";
import { SidebarProvider, useSidebar } from "@/components/ui/sidebar";
import { createSampleEvents } from "@/lib/sample-events";

/** The calendars the sidebar lists, in two accounts */
const CALENDARS: CalendarInfo[] = [
  {
    id: "you@example.com",
    name: "you@example.com",
    color: "red",
    email: "you@example.com",
  },
  {
    id: "personal",
    name: "Personal",
    color: "purple",
    email: "you@example.com",
  },
  {
    id: "holidays",
    name: "Holidays in Brazil",
    color: "green",
    email: "you@example.com",
    isSubscribed: true,
  },
  {
    id: "work",
    name: "Work",
    color: "blue",
    email: "you@work.example.com",
  },
];

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

  return (
    <CalendarProvider
      defaultEvents={initialEvents}
      defaultNumberOfDays={3}
      calendars={CALENDARS}
      // The mini calendar's week numbers follow this setting
      defaultViewSettings={{ showWeekNumbers: true }}
    >
      {/* The inline sidebar is position: fixed; the transform keeps it in this frame */}
      <SidebarProvider className="h-full min-h-0 [transform:translateZ(0)]">
        <CalendarWithSidebar />
      </SidebarProvider>
    </CalendarProvider>
  );
}

function CalendarWithSidebar() {
  // Phones get the sidebar as an overlay, closed until opened
  const { isMobile } = useSidebar();
  const { monthName, year, goToPrev, goToNext } = useCalendar();
  const [open, setOpen] = React.useState(true);
  const [overlayOpen, setOverlayOpen] = React.useState(false);

  const toggleSidebar = () => {
    if (isMobile) {
      setOverlayOpen((prev) => !prev);
      return;
    }
    setOpen((prev) => !prev);
  };

  return (
    <>
      <CalendarSidebar
        open={isMobile ? overlayOpen : open}
        onOpenChange={setOverlayOpen}
        overlay={isMobile}
        className="h-full"
      />
      <div className="flex min-w-0 flex-1 flex-col overflow-hidden">
        <header className="flex h-14 shrink-0 items-center gap-2 px-2">
          <Button
            variant="ghost"
            size="icon"
            className="size-7 text-muted-foreground"
            onClick={toggleSidebar}
          >
            <PanelLeftIcon />
            <span className="sr-only">Toggle calendar sidebar</span>
          </Button>
          <h2 className="flex-1 truncate text-base font-extrabold">
            {monthName} {year}
          </h2>
          <Button
            variant="ghost"
            size="icon"
            className="size-7 text-muted-foreground"
            onClick={goToPrev}
          >
            <ChevronLeftIcon />
            <span className="sr-only">Previous days</span>
          </Button>
          <Button
            variant="ghost"
            size="icon"
            className="size-7 text-muted-foreground"
            onClick={goToNext}
          >
            <ChevronRightIcon />
            <span className="sr-only">Next days</span>
          </Button>
        </header>
        <div className="flex flex-1 flex-col overflow-hidden">
          <WeekView scrollToHour={8} />
        </div>
      </div>
    </>
  );
}
```

Calendar Sidebar is the left column of the [live demo](/), modeled on Notion Calendar's: the [Mini Calendar](/docs/components/mini-calendar), a scheduling row and a "Meet with..." field, the [Calendar List](/docs/components/calendar-list), "Add calendar account" when you pass `onAddCalendarAccount`, and a footer with the [Theme Toggle](/docs/components/theme-toggle). On wide screens it's a fixed column that pushes the page over; on phones it opens as a sheet from the left ([Sidebar Overlay](/docs/components/sidebar-overlay)).

It reads the date, view and calendars from the surrounding [`CalendarProvider`](/docs/components/calendar-core), so the mini calendar follows the calendar as it moves, numbers its weeks while the provider's week numbers are on, and picking a day goes there (with weekends hidden, a Saturday or Sunday opens the Monday after it in day view). The "Meet with..." field meets with the provider's `contacts` (see [Meeting with people](#meeting-with-people)). Inside a [`SchedulingProvider`](/docs/components/scheduling), the Scheduling row starts marking open times to share, or opens a menu of scheduling links when your app creates them; without one, the row isn't there. "Add calendar account" calls your `onAddCalendarAccount`, to connect an account your way; the live demo adds an .ics file as a calendar. The file is yours, so wire them up there.

## Installation

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

Or install it by hand:

1. Install the items it builds on: `@calendarcn/calendar-core`, `@calendarcn/mini-calendar`, `@calendarcn/calendar-list`, `@calendarcn/sidebar-overlay`, `@calendarcn/theme-toggle`
2. Install the dependencies: `npm install lucide-react`
3. Add the shadcn/ui components it uses: `npx shadcn add button dropdown-menu kbd sidebar tooltip`
4. Copy these files into your project, keeping the paths under your components, hooks and lib folders:
   - [`components/calendar-sidebar.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/calendar-sidebar.tsx)
   - [`components/calendar-sidebar-people.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/calendar-sidebar-people.tsx)

## Usage

The sidebar is built from shadcn/ui's sidebar parts, so it needs a `SidebarProvider` around it, inside the `CalendarProvider`. Put it first in the provider's row, with the calendar beside it:

```tsx
import { CalendarProvider } from "@/components/calendar-provider";
import { CalendarSidebar } from "@/components/calendar-sidebar";
import { SidebarProvider } from "@/components/ui/sidebar";
import { WeekView } from "@/components/week-view";

export function CalendarPage() {
  return (
    <CalendarProvider defaultEvents={events} calendars={calendars}>
      <SidebarProvider className="h-screen">
        <CalendarSidebar />
        <div className="flex min-w-0 flex-1 flex-col">
          <WeekView />
        </div>
      </SidebarProvider>
    </CalendarProvider>
  );
}
```

The sidebar owns no open state: pass `open` to show or hide it. On phones, pass `overlay` and close the sheet from `onOpenChange`, which it calls on an outside tap, `Esc`, its close button and after a day is picked. The demo keeps one state per layout, so the overlay doesn't pop open when the window narrows:

```tsx
function Sidebar() {
  const { isMobile } = useSidebar();
  const [open, setOpen] = React.useState(true);
  const [overlayOpen, setOverlayOpen] = React.useState(false);

  return (
    <CalendarSidebar
      open={isMobile ? overlayOpen : open}
      onOpenChange={setOverlayOpen}
      overlay={isMobile}
    />
  );
}
```

Add your own buttons to the footer, before the theme toggle, with `footerActions`. The demo puts its docs and GitHub links there:

```tsx
<CalendarSidebar
  footerActions={
    <Button variant="ghost" size="icon" className="size-7" asChild>
      <a href="/help">
        <CircleHelpIcon />
        <span className="sr-only">Help</span>
      </a>
    </Button>
  }
/>
```

### Hiding calendars

The list's eye buttons hide and show calendars. Hiding only dims the row; to take a calendar's events off the views, give the provider only the shown events and merge its changes back into your full list. `filterShownEvents()` and `mergeShownEvents()` from `@/lib/event-utils` do both, and [Calendar App](/docs/components/calendar-app) does this for you:

```tsx
const [hiddenCalendarIds, setHiddenCalendarIds] = React.useState<string[]>([]);

<CalendarProvider
  events={filterShownEvents(events, hiddenCalendarIds)}
  onEventsChange={(shown) =>
    setEvents(mergeShownEvents(events, shown, hiddenCalendarIds))
  }
  calendars={calendars}
>
  <SidebarProvider>
    <CalendarSidebar
      hiddenCalendarIds={hiddenCalendarIds}
      onHiddenCalendarIdsChange={setHiddenCalendarIds}
    />
    {/* ... */}
  </SidebarProvider>
</CalendarProvider>;
```

### Meeting with people

The "Meet with..." field picks people from the provider's `contacts`, as Notion Calendar's does: focusing it lists the recent ones, typing lists the matches (or the typed address), the arrow keys move through them and `Enter` or a click picks one. `Esc` closes the list and clears the field. While you type, F, P and the calendar's other keys type into the field.

Picking someone adds them to a "Meeting participants" section under the field: their events show beside yours in the day and week views and the times you're all free are highlighted ([Meeting with people](/docs/components/calendar-core#meeting-with-people)). Hover a row to stop meeting with that person, or press "Clear" to stop meeting with everyone. Teammates added with "Show teammate calendar..." ([People Picker](/docs/components/people-picker)) are listed under "Team calendars", each with a button to remove them. Both lists live in the provider, through [`useCalendarPeople()`](/docs/components/calendar-core#usecalendarpeople), so the sidebar takes no props for them.

### Colors

The sidebars bring Notion Calendar's colors as their own tokens, added to your CSS file on install: `--calendar-sidebar`, `--calendar-sidebar-foreground`, `--calendar-sidebar-muted-foreground`, `--calendar-sidebar-primary` and the rest of shadcn/ui's sidebar set, each with a `calendar-` prefix. Inside the sidebar they replace your `--sidebar-*` tokens, so the rest of your app keeps its own sidebar theme. Change them in your CSS to restyle both sidebars.

## Features

- The mini calendar shows the month of the days on screen, highlights them, and marks today. Browse months with its arrows; the next navigation brings it back.
- Picking a day goes to its period in the current view: the day in day view, its week in week view.
- Scheduling starts marking the times you're free, like `S`, and leaves again on a second click. On phones the sheet closes so you can mark on the grid.
- "Meet with..." adds people from your contacts; the ones you meet with and the teammates shown are listed under it, each removable.
- Calendars are grouped by account, each account collapsible. Hover a calendar to show or hide it.
- The theme toggle cycles system, light and dark.
- On phones, the sheet closes on an outside tap, `Esc`, its close button (where the header's toggle sits) or a day pick.

## API Reference

### CalendarSidebar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `true` | Whether the sidebar shows. Inline, a closed sidebar gives its width back to the page. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the overlay asks to close: an outside tap, Esc, its close button, or a day picked in the mini calendar. |
| `overlay` | `boolean` | `false` | Renders the sidebar as a sheet from the left (phones). |
| `footerActions` | `ReactNode` | – | Buttons shown in the footer, before the theme toggle. |
| `hiddenCalendarIds` | `string[]` | – | Ids of the hidden calendars (controlled). |
| `defaultHiddenCalendarIds` | `string[]` | `[]` | Ids of the calendars hidden at first (uncontrolled). |
| `onHiddenCalendarIdsChange` | `(hiddenCalendarIds: string[]) => void` | – | Called with the new hidden ids when a calendar is shown or hidden. |
| `onAddCalendarAccount` | `() => void` | – | Adds "Add calendar account" below the calendars, which calls it. Without it, the row isn't drawn. |
| `className` | `string` | – | Classes for the inline sidebar's fixed column, e.g. `h-full` to fit a container that isn't the viewport. |

`CALENDAR_SIDEBAR_WIDTH` (`15rem`) is the sidebar's width, inline and as an overlay.
