# Sidebar Overlay

A sidebar shown as a sheet on narrow screens.

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

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

import * as React from "react";
import { CalendarDays, Inbox, Settings } from "lucide-react";

import { SidebarOverlay } from "@/components/sidebar-overlay";
import { Button } from "@/components/ui/button";

/** Rows of the example sidebar */
const ITEMS = [
  { label: "Calendar", icon: CalendarDays },
  { label: "Inbox", icon: Inbox },
  { label: "Settings", icon: Settings },
];

export function SidebarOverlayDemo() {
  const [open, setOpen] = React.useState(false);
  const [side, setSide] = React.useState<"left" | "right">("left");

  const openFrom = (nextSide: "left" | "right") => {
    setSide(nextSide);
    setOpen(true);
  };

  return (
    <div className="flex h-full items-center justify-center gap-2">
      <Button variant="outline" onClick={() => openFrom("left")}>
        Open from the left
      </Button>
      <Button variant="outline" onClick={() => openFrom("right")}>
        Open from the right
      </Button>
      <SidebarOverlay
        open={open}
        onOpenChange={setOpen}
        side={side}
        title="Example sidebar"
        description="A sidebar shown as a sheet."
        style={{ "--sidebar-width": "15rem" } as React.CSSProperties}
      >
        <div className="flex h-14 shrink-0 items-center px-4 text-sm font-semibold text-sidebar-primary">
          Workspace
        </div>
        <nav className="flex flex-col gap-0.5 px-2">
          {ITEMS.map(({ label, icon: Icon }) => (
            <button
              key={label}
              type="button"
              className="flex h-8 items-center gap-2 rounded-sm px-2 text-sm text-sidebar-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground"
              onClick={() => setOpen(false)}
            >
              <Icon className="size-4" />
              {label}
            </button>
          ))}
        </nav>
      </SidebarOverlay>
    </div>
  );
}
```

Sidebar Overlay shows a sidebar's content as a modal sheet from the left or the right. The [Calendar Sidebar](/docs/components/calendar-sidebar) and the [Details Sidebar](/docs/components/details-sidebar) use it on phones. It's the same sheet as shadcn/ui's `Sidebar` on mobile, but you own its open state and the breakpoint, so a sidebar can turn into an overlay at any width.

## Installation

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

Or install it by hand:

1. Add the shadcn/ui components it uses: `npx shadcn add sheet`
2. Copy these files into your project, keeping the paths under your components, hooks and lib folders:
   - [`components/sidebar-overlay.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/sidebar-overlay.tsx)

It also adds the sidebars' color tokens to your CSS: see [Colors](/docs/components/calendar-sidebar#colors).

## Usage

```tsx
import { SidebarOverlay } from "@/components/sidebar-overlay";

export function MobileNav() {
  const [open, setOpen] = React.useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Menu</Button>
      <SidebarOverlay
        open={open}
        onOpenChange={setOpen}
        side="left"
        title="Navigation"
        description="Pages of the app."
        style={{ "--sidebar-width": "15rem" } as React.CSSProperties}
      >
        <nav>{/* ... */}</nav>
      </SidebarOverlay>
    </>
  );
}
```

The sheet is as wide as `--sidebar-width`, up to 85% of the screen. Its title and description are for screen readers only.

## Features

- Closes on an outside tap and `Esc`, with focus kept inside while it's open.
- Opening focuses the sheet itself, not its first field, so a search field doesn't pop up a phone's keyboard.
- Works with shadcn/ui on Radix and on Base UI.

## API Reference

### SidebarOverlay

| Prop | Type | Description |
| --- | --- | --- |
| `open` (required) | `boolean` | Whether the sheet is open. |
| `onOpenChange` (required) | `(open: boolean) => void` | Called when the sheet asks to open or close. |
| `side` (required) | `"left" \| "right"` | Edge the sheet slides in from. |
| `title` (required) | `string` | Accessible name of the sheet (visually hidden). |
| `description` (required) | `string` | Accessible description of the sheet (visually hidden). |
| `className` | `string` | Classes for the sheet. |
| `style` | `CSSProperties` | Styles for the sheet, e.g. its `--sidebar-width`. |

`CALENDAR_SIDEBAR_COLORS_CLASS` points shadcn/ui's `--sidebar-*` colors at the `--calendar-sidebar-*` tokens for an element and what's inside it. The sheet and both calendar sidebars use it.
