chrome.commands

Description: Use the commands API to add keyboard shortcuts that trigger actions in your extension, for example, an action to open the browser action or send a command to the extension.
Availability: On target to be stable in Chrome 25
Permissions: None

Manifest

You must set manifest_version to (at least) 2 to use this API.

Usage

The commands API allows you to define specific commands, and bind them to a default key combination. Each command your extension accepts must be listed in the manifest as an attribute of the 'commands' manifest key. Note: Combinations that involve Ctrl+Alt are not permitted in order to avoid conflicts with the AltGr key. Also note that on Mac 'Ctrl' is automatically converted to 'Command'. If you want 'Ctrl' instead, please specify 'MacCtrl'.

{
  "name": "My extension",
  ...
  "commands": {
    "toggle-feature-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y"
      },
      "description": "Toggle feature foo"
    },
    "_execute_browser_action": {
      "suggested_key": {
        "windows": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y",
        "chromeos": "Ctrl+Shift+U",
        "linux": "Ctrl+Shift+J"
      }
    },
    "_execute_page_action": {
      "suggested_key": {
        "default": "Ctrl+E"
        "windows": "Alt+P",
        "mac": "Option+P",
      }
    }
  },
  ...
}

In your background page, you can bind a handler to each of the commands defined in the manifest (except for '_execute_browser_action' and '_execute_page_action') via onCommand.addListener. For example:

chrome.commands.onCommand.addListener(function(command) {
  console.log('Command:', command);
});

The '_execute_browser_action' and '_execute_page_action' commands are reserved for the action of opening your extension's popups. They won't normally generate events that you can handle. If you need to take action based on your popup opening, consider listening for an 'onDomReady' event inside your popup's code.

chrome.commands reference

Types

Command

Properties of Command

name ( optional string )
The name of the Extension Command
description ( optional string )
The Extension Command description
shortcut ( optional string )
The shortcut active for this command, or blank if not active.

Methods

getAll

chrome.commands.getAll(function callback)

Returns all the registered extension commands for this extension and their shortcut (if active).

Parameters

callback ( optional function )
Called to return the registered commands.

Callback

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of Command commands) {...};
commands ( array of Command )

Events

onCommand

chrome.commands.onCommand.addListener(function(string command) {...});

Fired when a registered command is activated using a keyboard shortcut.

Listener Parameters

command ( string )

Sample Apps that use chrome.commands

  • MiniCodeEdit – A very small code editor.