> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Keyboard shortcuts

The editor's keys follow Word on each platform: ⌘ on a Mac, Ctrl on Windows and Linux. Each key runs a command id, as in VS Code, so you can change any key in code and your users can change keys in the editor.

## How it works

* A **command** has an id (`format.bold`, `edit.repeat`, `cursor.wordLeft`), a title and a category.
* A **binding** joins a key to a command: `{ key: "mod+b", command: "format.bold" }`. `mod` is ⌘ on a Mac and Ctrl elsewhere.
* Bindings come in three layers. A later layer wins:
  1. Word's defaults (`DOCX_KEYBINDINGS`)
  2. your `overrides`
  3. the user's changes, from the Keyboard Shortcuts window

## Change keys in code

```ts theme={null}
import { mountDocxEditor } from "@reductoai/docx-editor";

const editor = mountDocxEditor(el, {
  keybindings: {
    overrides: [
      { key: "mod+shift+b", command: "format.bold" },
      { key: "mod+k mod+c", command: "insert.comment" }, // a chord: two presses
      { key: "alt+down", command: "table.columnEnd", when: "inTable" },
      { command: "-format.underline" }, // "-id" removes a command's keys
    ],
  },
});
```

In React, pass the same object as the `keybindings` prop.

### Key names

Modifiers are `mod`, `meta`, `ctrl`, `alt` and `shift`, in any order. Keys are the letter or digit, `f1` to `f12`, `enter`, `tab`, `space`, `backspace`, `delete`, `escape`, `up`, `down`, `left`, `right`, `home`, `end`, `pageup`, `pagedown`, `contextmenu` and punctuation such as `[`, `=` or `.`. The editor reads the physical key, so ⌥ on a Mac still binds as `alt+`.

Keys that the browser keeps for itself cannot work: Ctrl+W, Ctrl+T, Ctrl+N, Ctrl+Tab, and ⌘Q and ⌘W on a Mac. The browser never sends them to the page, and the Keyboard Shortcuts window refuses them. A binding that does not parse is skipped with a `console.warn`.

### `when`

A `when` clause limits a binding to a state of the editor. It reads these names, with `!`, `&&`, `||` and parentheses:

| Name | True when |
| - | - |
| `readOnly` | the document is open for reading only |
| `suggesting` | Track Changes is on |
| `inTable` | the caret is in a table cell |
| `inList` | the caret is in a list item |
| `pictureSelected` | a picture is selected |
| `hasSelection` | the selection is not empty |
| `inStory` | the caret is in a header, footer, note or text box |
| `navOpen` | the Navigation pane is open |
| `atParagraphStart` | the caret is at the start of a paragraph |

Add your own with `model.keys.setContext("myPanelOpen", true)`.

If a command declines a key (a table move outside a table), the next binding of that key runs.

## Add a command

```ts theme={null}
const off = editor.model.keys.register({
  id: "app.save",
  title: "Save",
  category: "File",
  run: (model) => save(model),
});
editor.model.keys.bind({ key: "mod+s", command: "app.save" });
```

`run` returns `false` to decline the key. `register` returns a function that removes the command.

## Read keys for your UI

```ts theme={null}
model.keys.label("format.bold"); // "⌘B" or "Ctrl+B"
model.keys.title("format.bold"); // "Bold (⌘B)", for a tooltip
model.keys.list();               // every command, its keys, its whens and its source
model.keys.run("edit.repeat");   // run a command without a key
```

The labels follow the user's changes. The built-in toolbar, context menu and command palette read them.

## The user's changes

The Keyboard Shortcuts window lists every command. The user opens it with the keyboard button at the end of the toolbar, or from the command palette (⌘⇧P / Ctrl+Shift+P, then *Keyboard shortcuts*). With `customizable: false` the button and the window are hidden. They can search by name or key, record new keys (a chord too), see which command already has a key, and reset one command or all.

The changes are kept in `localStorage` under `"docx-editor:keybindings"`. Only the changes are kept, so a new default in a later release still reaches a user who did not change that command. To keep them somewhere else, pass a store:

```ts theme={null}
import { memoryKeybindings, type KeybindingStore } from "@reductoai/docx-editor";

const serverStore: KeybindingStore = {
  load: () => fetch("/me/keys").then((r) => (r.ok ? r.json() : null)),
  save: (value) => void fetch("/me/keys", { method: "PUT", body: JSON.stringify(value) }),
};

mountDocxEditor(el, { keybindings: { store: serverStore } });
```

* `store: null` keeps changes for the page only. `memoryKeybindings()` does the same and lets you read them.
* `customizable: false` hides the window.
* `model.keys.exportJson()` and `importJson(text)` move the changes as a file.

## The command palette

⌘⇧P / Ctrl+Shift+P opens the editor's command palette. Each row shows its keys. ⌘K stays Word's *Insert link*. If your app has its own palette on ⌘K, bind the key and send the command there:

```ts theme={null}
import { PALETTE_ON_MOD_K, routePalette } from "@reductoai/docx-editor";

const editor = mountDocxEditor(el, { keybindings: { overrides: [PALETTE_ON_MOD_K] } });
const unroute = routePalette(editor.model, () => myPalette.toggle());
```

Reference: [Keyboard shortcuts API](https://docs.reducto.ai/office/docx/api/keyboard.md).
