commands
========

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example | 
```json
"commands": {
  "toggle-feature": {
    "suggested\_key": {
      "default": "Ctrl+Shift+Y",
      "linux": "Ctrl+Shift+U"
    },
    "description": "Send a 'toggle-feature' event"
  }
}
```
 |

Use the **`commands`** key to define one or more keyboard shortcuts for your extension.

Each keyboard shortcut is defined with a **name**, a **combination of keys**, and a **description**. Once you've defined commands in your extension's `manifest.json`, you can listen for their associated key combinations with the `commands` JavaScript API.

Syntax
------

The `commands` key is an object, and each shortcut is a property of it. **The property's name is the name of the shortcut.**

Each shortcut's value is an object, with up to 2 properties:

1. `suggested_key`: the combination of keys that activate the shortcut.
2. `description`: a string that describes the shortcut; i.e. what it does.

The `suggested_key` property is an object with any of the following properties (all strings):

* `"default"`
* `"mac"`
* `"linux"`
* `"windows"`
* `"chromeos"`
* `"android"`
* `"ios"`

The value of each property is the keyboard shortcut for the command on that platform, as a string containing keys separated by "`+`". The value for `"default"` is used on all platforms that are not explicitly listed.

For example:


```json
"commands": {
  "toggle-feature": {
    "suggested\_key": {
      "default": "Alt+Shift+U",
      "linux": "Ctrl+Shift+U"
    },
    "description": "Send a 'toggle-feature' event to the extension"
  },
  "do-another-thing": {
    "suggested\_key": {
      "default": "Ctrl+Shift+Y"
    }
  }
}
```


This JSON defines 2 shortcuts:

1. `"toggle-feature"`, accessed with
 `Ctrl`
 +
 `Shift`
 +
 `U`
 on Linux, and
 `Alt`
 +
 `Shift`
 +
 `U`
 on all other platforms.
2. `"do-another-thing"`, accessed with
 `Ctrl`
 +
 `Shift`
 +
 `Y`
 on all platforms.

You could then listen for the `"toggle-feature"` command with code like this:


```js
browser.commands.onCommand.addListener((command) => {
  if (command === "toggle-feature") {
    console.log("Toggling the feature!");
  }
});
```

### Special shortcuts

There are these 4 **special shortcuts with default actions** for which the `commands.onCommand` event does not fire:

* `_execute_browser_action`: works like a click on a toolbar button created with `browserAction` or specified in the browser\_action key in the manifest.json key.
* `_execute_action`: works like a click on a toolbar button created with `action` or specified in the action key in the manifest.json key.
* `_execute_page_action`: works like a click on an address bar button created with `pageAction` or specified in the page\_action key in the manifest.json key.
* `_execute_sidebar_action`: opens the extension's sidebar specified in the sidebar\_action manifest.json key.

The availability of these special shortcuts varies between manifest versions and browsers, like this:

|  | Manifest V2 | Manifest V3 |
| --- | --- | --- |
| `_execute_browser_action` | Yes | No |
| `_execute_action` | No | Yes |
| `_execute_page_action` | Yes | Not available in Chromium-based browsers |
| `_execute_sidebar_action` | Firefox only | Firefox only |

For example, this JSON defines a key combination that clicks the extension's browser action:


```json
"commands": {
  "\_execute\_browser\_action": {
    "suggested\_key": {
      "default": "Ctrl+Shift+Y"
    }
  }
}
```

Shortcut values
---------------

There are two valid formats for shortcut keys: as a **key combination** or as a **media key**.

### Key combinations

**Note:** On Macs, `"Ctrl"` is interpreted as `"Command"`, so if you actually need `"Ctrl"`, specify `"MacCtrl"`.

Key combinations must consist of 2 or 3 keys:

1. **modifier** (mandatory, except for function keys). This can be any of: `"Ctrl"`, `"Alt"`, `"Command"`, or `"MacCtrl"`.
2. **secondary modifier** (optional). If supplied, this must be either `"Shift"` or (for Firefox ≥ 63) any one of `"Ctrl"`, `"Alt"`, `"Command"`, or `"MacCtrl"`. Must not be the modifier already used as the main modifier.
3. **key** (mandatory). This can be any one of:
    * the letters `A` – `Z`
    * the numbers `0` – `9`
    * the function keys `F1` – `F12`
    * `Comma`, `Period`, `Home`, `End`, `PageUp`, `PageDown`, `Space`, `Insert`, `Delete`, `Up`, `Down`, `Left`, `Right`

The key is then given as a string containing the set of key values, in the order listed above, separated by "`+`". For example, `"Ctrl+Shift+Z"`.

If a key combination is already used by the browser (like `"Ctrl+P"`) or by an existing add-on, then you can't override it. You can define it, but your event handler will not be called when the user presses the key combination.

### Media keys

Alternatively, the shortcut may be specified as one of the following media keys:

* `"MediaNextTrack"`
* `"MediaPlayPause"`
* `"MediaPrevTrack"`
* `"MediaStop"`
Updating shortcuts
------------------

Shortcuts can be updated via `commands.update()`. Users can also update shortcuts via the "Manage Extension Shortcuts" option at `about:addons` in Firefox, as shown in this video. In Chrome, users can change shortcuts at `chrome://extensions/shortcuts`.

Example
-------

Define a single keyboard shortcut, using only the default key combination:


```json
"commands": {
  "toggle-feature": {
    "suggested\_key": {
      "default": "Ctrl+Shift+Y"
    },
    "description": "Send a 'toggle-feature' event"
  }
}
```


Define two keyboard shortcuts, one with a platform-specific key combination:


```json
"commands": {
  "toggle-feature": {
    "suggested\_key": {
      "default": "Alt+Shift+U",
      "linux": "Ctrl+Shift+U"
    },
    "description": "Send a 'toggle-feature' event"
  },
  "do-another-thing": {
    "suggested\_key": {
      "default": "Ctrl+Shift+Y"
    }
  }
}
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.