commands

"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 add-on.

Each shortcut is defined with a name, a combination of keys, and a description. Once you've defined some commands in manifest.json, you can listen for the associated key combinations using 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 is itself an object, which has up to two properties:

• suggested_key: this defines the combination of keys
• description: a string that describes this shortcut

The suggested_key property is itself an object, that may have any of the following properties, which are all strings:

• "default", "mac", "linux", "windows", "chromeos", "android", "ios"

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

For example:

"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 defines two shortcuts:

• one named "toggle-feature", accessed using Ctrl+Shift+U on Linux, and Alt+Shift+U on all other platforms
• one named "do-another-thing", accessed using Ctrl+Shift+Y on all platforms.

You could then listen for the first of these commands with code like this:

chrome.commands.onCommand.addListener(function(command) {
  if (command == "toggle-feature") {
    console.log("toggling the feature!");
  }
});

Shortcut values

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

Key combinations

Key combinations must consist of two or three keys:

• modifier (mandatory). This can be any of: "Ctrl", "Alt", "Command", "MacCtrl".
• secondary modifier (optional). If supplied, this must be "Shift".
• key (mandatory). This can be any one of:
  • the letters A-Z
  • the numbers 0-9
  • Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete, Up, Down, Left, Right

If a key combination is already used by the browser (for example, "Ctrl+Shift+R"), or by an existing add-on, then you can't override it. You will be allowed to define it, but your event handler will not be called when the user enters it.

Media keys

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

• "MediaNextTrack", "MediaPlayPause", "MediaPrevTrack", "MediaStop"

Chrome incompatibilities

commands

Firefox does not support:

• Media keys as shortcuts
• global
• the special command _execute_browser_action

Example

Define a single shortcut, using only the default:

"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    },
    "description": "Send a 'toggle-feature' event"
  }
}

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

"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"
    }
  }
}