# Command Menu

The live demo's ⌘K menu, for creating an event, going to a typed date, today, previous and next, switching views, and your app's own commands.

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

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

import * as React from "react";

import { CalendarProvider } from "@/components/calendar-provider";
import { CommandMenu } from "@/components/command-menu";
import { Button } from "@/components/ui/button";
import { WeekView } from "@/components/week-view";
import { createSampleEvents } from "@/lib/sample-events";

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

  return (
    <CalendarProvider defaultEvents={initialEvents}>
      <div className="flex h-full flex-col">
        <div className="flex h-12 shrink-0 items-center border-b px-3">
          <Button variant="outline" size="sm" onClick={() => setOpen(true)}>
            Open command menu
          </Button>
        </div>
        <div className="flex min-h-0 flex-1 flex-col">
          <WeekView scrollToHour={8} />
        </div>
      </div>
      {/* A button here, to leave ⌘K to the docs' search. In your app, open it
          with useCalendarShortcuts({ onToggleCommandMenu }) */}
      <CommandMenu open={open} onOpenChange={setOpen} />
    </CalendarProvider>
  );
}
```

`CommandMenu` is the [live demo](/)'s `⌘K` menu, built on shadcn/ui's [Command](https://ui.shadcn.com/docs/components/command) in a Dialog. Creating an event, going to a date, today, previous and next, the day, week, month, year and agenda views, "Select all visible" (`⌘A`), the view settings ("Hide weekends", "Hide declined events" and "Hide week numbers", which read "Show …" while the setting is off, as in Notion Calendar), the week start ("Start week on..."), the number of days ("Set number of displayed days...") and the hour size ("Default hour size", "Zoom hours in", "Zoom hours out") come from [`useCalendar()`](/docs/components/calendar-core#usecalendar), so it goes inside `CalendarProvider`. Commands that belong to your app, such as its panels, event search, the shortcut list, its theme and .ics files, show only when you pass their callback.

## Installation

```bash
npx shadcn add @calendarcn/command-menu
```

Or install it by hand:

1. Install the items it builds on: `@calendarcn/calendar-core`
2. Add the shadcn/ui components it uses: `npx shadcn add command dialog kbd`
3. Copy these files into your project, keeping the paths under your components, hooks and lib folders:
   - [`components/command-menu.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/command-menu.tsx)
   - [`components/time-zone-list.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/time-zone-list.tsx)
   - [`lib/date-query.ts`](https://github.com/vmnog/calendarcn/blob/main/src/lib/date-query.ts)

## Usage

```tsx
import { useCalendarShortcuts } from "@/hooks/use-calendar-shortcuts";
import { CalendarProvider } from "@/components/calendar-provider";
import { CommandMenu } from "@/components/command-menu";
import { WeekView } from "@/components/week-view";

export function Schedule() {
  return (
    <CalendarProvider defaultEvents={events}>
      <CalendarWithMenu />
    </CalendarProvider>
  );
}

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

  // ⌘K / Ctrl+K opens and closes the menu, even from a text field
  useCalendarShortcuts({ onToggleCommandMenu: () => setOpen((o) => !o) });

  return (
    <>
      <WeekView />
      <CommandMenu open={open} onOpenChange={setOpen} />
    </>
  );
}
```

The menu is controlled: it opens and closes through `open` and `onOpenChange`, and closes before it runs a command. The preview opens it from a button, to leave `⌘K` to this site's search.

### Go to date

"Go to date..." turns the menu's field into a date field, as in Notion Calendar. Type a date and the menu shows the day it reads, with its weekday, so you can check "next friday" before going there. `Enter` shows that day's period in the current view and briefly highlights it (`navigateToDate`). `Esc` closes the menu without moving, and `⌫` in the empty field goes back to the commands.

It reads "today", "tomorrow", weekdays ("friday", "next friday", "last monday"), "next week", "next month", "in 2 weeks", "3 days ago", "+3d", a month and day in either order ("dec 25", "25 december", "December 25th, 2027", "sept 5"), a month alone ("jan"), a numeric date in the locale's order ("12/25", or "25/12" in en-GB, "25.12." in German) and "2027-12-25". A date without a year is the next one from today, and weeks start on the provider's `weekStartsOn`. Month and weekday names work in the provider's `locale` and in English. The parser is `parseDateQuery()` in `lib/date-query.ts`, which the CLI installs with the menu:

```ts
import { parseDateQuery } from "@/lib/date-query";

parseDateQuery("next friday", { today: new Date(), locale, weekStartsOn });
// → the Friday of next week, at midnight, or null when the text isn't a date
```

To open the menu straight on Go to date, as the `.` key does in the demo, pass `defaultPage="go-to-date"` before opening it:

```tsx
const [page, setPage] = React.useState<CommandMenuPage>("commands");

useCalendarShortcuts({
  onToggleCommandMenu: () => {
    setPage("commands");
    setOpen((o) => !o);
  },
  onGoToDate: () => {
    setPage("go-to-date");
    setOpen(true);
  },
});

<CommandMenu open={open} onOpenChange={setOpen} defaultPage={page} />;
```

### Create event

"Create event..." (`C` outside the menu) starts a new event at the next half hour, as Notion Calendar does: on today when it's on screen, else on the first day shown (`addEventAtNextSlot`), all-day in month view. It goes through your `createEvent` and is a [draft](/docs/components/calendar-core#creating-events) with its title focused: its first edit saves it, and undo and the details then work as for any new event.

### Second lists

"Start week on..." and "Set number of displayed days..." open a second list in the same menu, as Notion Calendar's do: the days of the week other than the one the week starts on now ("Mondays", "Tuesdays", ...), or the day counts 2 to 9. Type to filter them, `↵` picks one, `⌫` in the empty search goes back to the commands, and `Esc` closes the menu.

### Your app's commands

Pass a callback to add its command. These are the demo's:

```tsx
<CommandMenu
  open={open}
  onOpenChange={setOpen}
  onToggleSidebar={toggleSidebar}
  onToggleContextPanel={toggleContextPanel}
  onCycleTheme={cycleTheme}
  onImportIcs={() => fileInputRef.current?.click()}
  onExportIcs={exportIcs}
  onOpenSettings={openSettings}
  onAddCalendarAccount={addCalendarAccount}
  onManageCalendarAccounts={manageCalendarAccounts}
  onSupport={() => window.open(ISSUES_URL, "_blank")}
  onAbout={() => router.push("/docs")}
  onSearchEvents={(query) => detailsActions.current?.searchEvents(query)}
  onShowShortcuts={() => detailsActions.current?.showAllShortcuts()}
  onMeetWith={() => openPeoplePicker("meet-with")}
  onShowTeammateCalendar={() => openPeoplePicker("teammate")}
  showComingSoon
/>
```

- `onImportIcs` and `onExportIcs` add "Import .ics file..." and "Export .ics file". Read and write the files with [`@calendarcn/ics`](/docs/import-export): the demo opens a hidden `<input type="file">`, passes its text to `parseIcs()` and adds the events, and downloads `toIcs(events)` as a file.
- `onCycleTheme` adds "Set theme...". The demo goes from system to light to dark with `useTheme()` from next-themes.
- `onSearchEvents` adds "Search events", and once you type, "Search events for “…”" with your text. The demo opens the [Details Sidebar](/docs/components/details-sidebar)'s event search with the field focused.
- `onShowShortcuts` adds "Show keyboard shortcuts" (`?`). The demo shows the details sidebar's full list.
- `onMeetWith` and `onShowTeammateCalendar` add "Meet with..." (F) and "Show teammate calendar..." (P). The demo opens the [People Picker](/docs/components/people-picker) from both.
- `onToggleSidebar` and `onToggleContextPanel` add the panel toggles, next to the [Calendar Header](/docs/components/calendar-header)'s buttons.
- `onShareAvailability` adds "Share availability..." (`S`), and `onCreateSchedulingLink` adds "Create recurring scheduling link..." and "Create one-off scheduling link...", called with `"recurring"` or `"one-off"`. Calendar App passes them from [`useScheduling()`](/docs/components/scheduling#usescheduling); the link commands only when the app creates scheduling links.
- `onOpenSettings` adds "Go to settings" (`⌘,`). The demo opens the [Calendar Settings](/docs/components/calendar-settings) dialog.
- `onAddCalendarAccount` and `onManageCalendarAccounts` add "Add calendar account" and "Manage calendar accounts". The demo adds an .ics file as a calendar, and opens the settings on the calendars.
- `onSupport` adds "Support & feedback" and `onAbout` adds "About CalendarCN". The demo opens a new GitHub issue in a new tab, and the docs.
- `showComingSoon` also lists the Notion Calendar commands CalendarCN doesn't have yet, disabled with a "Soon" badge, as the demo does.

### Time zones

The "Time zones" commands come from `useCalendar()`, like going to today and the views, so they work in any calendar:

- "Travel to time zone..." draws the calendar in another zone for now, with your home zone beside it. See [Travel to a time zone](/docs/components/calendar-core#travel-to-a-time-zone).
- "Show additional time zones..." adds a zone's column beside the time axis.
- With more than one zone, "Make time zone primary..." and "Hide time zone..." pick one of the zones shown.

Each opens a list of zones in the menu's place, searched by city, zone name or offset ("Tokyo", "Japan", "+9"). `⌫` in an empty search goes back to the commands. Pass `timeZoneCommand="travel"` to open the menu on its list: the demo does that for `Z`, with [`useCalendarShortcuts({ onTravelToTimeZone })`](/docs/keyboard-shortcuts#app-shortcuts).

### Keyboard shortcuts

The menu shows each command's shortcut. Pass the same callbacks to [`useCalendarShortcuts()`](/docs/keyboard-shortcuts#app-shortcuts) to turn the keys on:

```tsx
useCalendarShortcuts({
  onToggleCommandMenu: () => setOpen((o) => !o),
  onToggleSidebar: toggleSidebar,
  onToggleContextPanel: toggleContextPanel,
  onCycleTheme: cycleTheme,
});
```

### Theming

The dialog is translucent and blurred in dark mode. The CLI also adds a rule to your CSS file that dims the page less behind the menu in dark mode (`rgb(0 0 0 / 0.3)`), found through the `data-command-menu` attribute on the dialog. The rest of the look comes from your own `command` and `dialog` components.

## API Reference

### CommandMenu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – | Whether the menu is open. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the menu opens or closes: on Escape, a click outside, or before a command runs. |
| `onToggleSidebar` | `() => void` | – | Adds "Toggle sidebar" (⌘ /). |
| `onToggleContextPanel` | `() => void` | – | Adds "Toggle context panel" (/). |
| `onCycleTheme` | `() => void` | – | Adds "Set theme..." (Shift M). |
| `onImportIcs` | `() => void` | – | Adds "Import .ics file...". |
| `onExportIcs` | `() => void` | – | Adds "Export .ics file". |
| `onShareAvailability` | `() => void` | – | Adds "Share availability..." (S). |
| `onCreateSchedulingLink` | `(kind: "recurring" \| "one-off") => void` | – | Adds "Create recurring scheduling link..." and "Create one-off scheduling link...". |
| `onOpenSettings` | `() => void` | – | Adds "Go to settings" (⌘ ,). |
| `onAddCalendarAccount` | `() => void` | – | Adds "Add calendar account". |
| `onManageCalendarAccounts` | `() => void` | – | Adds "Manage calendar accounts". |
| `onSupport` | `() => void` | – | Adds "Support & feedback". |
| `onAbout` | `() => void` | – | Adds "About CalendarCN". |
| `onMeetWith` | `() => void` | – | Adds "Meet with..." (F). |
| `onShowTeammateCalendar` | `() => void` | – | Adds "Show teammate calendar..." (P). |
| `onSearchEvents` | `(query: string) => void` | – | Adds "Search events" (called with an empty query) and, once text is typed, "Search events for “…”" (called with that text). |
| `onShowShortcuts` | `() => void` | – | Adds "Show keyboard shortcuts" (?). |
| `defaultPage` | `"commands" \| "go-to-date"` | `"commands"` | The page the menu opens on, each time it opens: its commands, or Go to date's field. |
| `showComingSoon` | `boolean` | `false` | Also lists the commands CalendarCN doesn't have yet, disabled with a "Soon" badge. |
| `timeZoneCommand` | `"travel" \| "add" \| "primary" \| "hide"` | – | Opens the menu on that time zone command's list instead of the commands, e.g. `"travel"` for the Z key. |
