# Keyboard shortcuts

Move around the calendar without touching the mouse.

The [Calendar](/docs/components/calendar) block and the [live demo](/) share a set of single-key shortcuts. Single-key shortcuts pause while you type in an input, a select or editable content, and leave presses with `⌘`, `Ctrl` or `Alt` to your app and the browser, apart from the event keys below.

They come from `useCalendarShortcuts()`, part of [Calendar Core](/docs/components/calendar-core), not from the views. A calendar you build from the views alone only handles keys while one of its events has focus: see [Keyboard & accessibility](/docs/components/calendar#keyboard--accessibility) for moving and resizing events from the keyboard.

## Navigation

| Action          | Shortcut        |
| --------------- | --------------- |
| Go to today     | `T`             |
| Previous period | `J` or `←`      |
| Next period     | `K` or `→`      |
| Go to date      | `.`, in the app |

Go to date comes with the [command menu](/docs/components/command-menu), so it's an app shortcut (below). It reads what you type the way Notion Calendar does: "today", "tomorrow", a weekday ("friday", "next friday", "last monday"), "next week", "in 2 weeks", "3 days ago", a month and day in either order ("dec 25", "25 december", "December 25th, 2027"), a numeric date in your locale's order ("12/25", or "25/12" in en-GB) and "2027-12-25". A date without a year is the next one from today, and "next friday" is the Friday of next week, counting weeks from the calendar's `weekStartsOn`. Month and weekday names work in the calendar's `locale` and in English.

## Views

| Action           | Shortcut     |
| ---------------- | ------------ |
| Day view         | `D` or `1`  |
| Week view        | `W` or `0` |
| Show 2 to 9 days | `2` to `9` |
| Month view       | `M`         |
| Year view        | `Y`         |
| Agenda view      | `A`         |

## Hour size

In day and week view, make the hours taller to read busy days, or shorter to see more of the day. Zooming keeps the middle of the screen where it was.

| Action            | Shortcut |
| ----------------- | -------- |
| Zoom hours in     | `⇧⌘.`     |
| Zoom hours out    | `⇧⌘,`     |
| Default hour size | `⇧⌘0`     |

Like the event keys, they work with `Ctrl` on Windows and Linux. See [Hour size](/docs/components/calendar-core#hour-size).

## Events

| Action                                    | Shortcut         |
| ----------------------------------------- | ---------------- |
| Start an event at the next half hour      | `C`             |
| Deselect event                            | `Esc`             |
| Travel back home, with no event selected  | `Esc`             |
| Select all visible                        | `⌘A`             |
| Delete the selected event                 | `Delete` or `⌫`     |
| Cut, copy or duplicate the selected event | `⌘X`, `⌘C`, `⌘D` |
| Paste                                     | `⌘V`             |
| Undo                                      | `⌘Z`             |
| Redo                                      | `⇧⌘Z`             |
| Show or hide weekends                     | `⇧⌘E`             |

`C` starts a new event at the next half hour, as in Notion Calendar: on
today when it's on screen, else on the day Go to date just went to, else on the
first day shown. In month view it is an all-day event. It is a
[draft](/docs/components/calendar-core#creating-events) with its title focused:
name it to save it, or press `Esc` twice to throw it away.

A paste goes where the mouse is: in day and week view the copy starts at the time slot under it, and in month view it lands on the day under it at its own time of day. With the mouse elsewhere it goes to the last spot it pointed at, while that is on screen, else to today, else to the first day on screen. All-day events stay all-day, and every paste is a new event. Undo covers creating, moving, resizing and editing events and every action above; see [Calendar Core](/docs/components/calendar-core#undo-and-redo).

These keys act only when they have something to act on (a selected event, something cut or copied, a change to undo or redo) and otherwise leave the press to the browser. They pause while you type in a field or compose text with an input method, and `⌘C` and `⌘X` also while text is selected on the page.

In a field or menu of the event details, `Esc` only closes it and restores the value from before. Press it again to deselect the event. For an event that is being [created](/docs/components/calendar-core#creating-events), that second `Esc` throws the draft away, and `Esc` while dragging to draw one drops it.

Shift-click or `⌘`-click on events selects several, and `⌘A` every event on screen (in a text field it still selects the text). The event keys then act on all of them, and `Alt+↑` and `Alt+↓` on one of them move them all. See [Selecting several events](/docs/components/calendar-core#selecting-several-events).

## Scheduling

The live demo ([Calendar App](/docs/components/calendar-app)) also has Notion Calendar's scheduling key, from `useSchedulingShortcuts()` inside a `SchedulingProvider`. See [Scheduling](/docs/components/scheduling).

| Action                                         | Shortcut     |
| ---------------------------------------------- | ------------ |
| Mark open times to share                       | `S`         |
| Leave without copying, while marking           | `Esc`         |
| Remove the selected marked time, while marking | `Delete` or `⌫` |

## App shortcuts

The live demo ([Calendar App](/docs/components/calendar-app)) adds keys for the parts around the calendar. They come from the same hook, each one on only when you pass its action, so a calendar without a command menu or panels never claims them:

| Action                            | Shortcut | Option                   |
| --------------------------------- | -------- | ------------------------ |
| Command menu                      | `⌘K`     | `onToggleCommandMenu`    |
| Toggle the sidebar                | `⌘/`     | `onToggleSidebar`        |
| Toggle the context panel          | `/`     | `onToggleContextPanel`   |
| Cycle theme (system, light, dark) | `⇧M`     | `onCycleTheme`           |
| Settings                          | `⌘,`     | `onOpenSettings`         |
| Go to date                        | `.`    | `onGoToDate`             |
| All keyboard shortcuts            | `?`    | `onShowShortcuts`        |
| Travel to time zone               | `Z`    | `onTravelToTimeZone`     |
| Meet with...                      | `F`    | `onMeetWith`             |
| Show teammate calendar...         | `P`    | `onShowTeammateCalendar` |

```tsx
useCalendarShortcuts({
  onToggleCommandMenu: () => setCommandMenuOpen((open) => !open),
  onToggleSidebar: toggleSidebar,
  onToggleContextPanel: toggleContextPanel,
  onCycleTheme: cycleTheme,
  onGoToDate: openGoToDate,
  onShowShortcuts: () => detailsSidebarActions.current?.showAllShortcuts(),
  onMeetWith: () => openPeoplePicker("meet-with"),
  onShowTeammateCalendar: () => openPeoplePicker("teammate"),
});
```

`F` and `P` open the [People
Picker](/docs/components/people-picker), to meet with someone or show a
teammate's calendar, as in Notion Calendar.

The live demo opens Go to date in the [Command Menu](/docs/components/command-menu#go-to-date) (`defaultPage="go-to-date"`), and the full list in the [Details Sidebar](/docs/components/details-sidebar#all-keyboard-shortcuts).

## The full list

`?` (or "Show keyboard shortcuts" in the command menu) shows every
shortcut on this page in the live demo's details sidebar, grouped as Notion
Calendar groups them: General, Workflows, Editing, Calendar view, Calendar
navigation and App navigation. Type in its field to find one by name or by key (
`t` finds "Go to today"), and press `Esc` to go back.

The list is data, `KEYBOARD_SHORTCUT_GROUPS` in `lib/keyboard-shortcuts.ts` ([Calendar Core](/docs/components/calendar-core)), with each key in `SHORTCUTS`. The details sidebar's "Useful shortcuts" read their keys from it too. If you change a key in the hook, change it there, so the list stays true.

On Windows and Linux, use `Ctrl` in place of `⌘`. The one exception is the sidebar toggle, which needs the `⌘` (Meta) key. `⌘K` and `⌘,` work from inside a text field too. The [Command Menu](/docs/components/command-menu) and the [Calendar Header](/docs/components/calendar-header) show these keys next to their commands and buttons.

## Use them in your own calendar

The Calendar block turns them on for you. In a calendar you compose yourself, call the hook anywhere inside `CalendarProvider`:

```tsx
import { useCalendarShortcuts } from "@/hooks/use-calendar-shortcuts";

function Shortcuts() {
  useCalendarShortcuts();
  return null;
}

<CalendarProvider defaultEvents={events}>
  <Shortcuts />
  <WeekView />
</CalendarProvider>;
```

The hook listens on `window`, so one calendar per page should have it.

### Turn them off

Pass `shortcuts={false}` to the Calendar block, or `useCalendarShortcuts({ enabled: false })` to the hook, for example while a dialog of yours is open.

### Change them

The hook is your code: the keys live in `handleShortcut()`, `handleEditShortcut()` and `handleAppShortcut()` in `hooks/use-calendar-shortcuts.ts`, so remap or remove them there, and in `lib/keyboard-shortcuts.ts` for the list. The app keys are checked before the calendar's, and one that runs stops the event from reaching later `keydown` listeners. To give your app another key the calendar also uses, handle it in a `keydown` listener added before the hook's and call `event.stopImmediatePropagation()`.
