Description

Manifest

Concepts and usage

The Commands API allows extension developers to define specific commands, and bind them to a defaultkey combination. Each command an extension accepts must be declared as properties of the"commands" object in theextension's manifest.

The property key is used as the command's name. Command objects can take two properties.

suggested_key

An optional property that declares default keyboard shortcuts for the command. If omitted, thecommand will be unbound. This property can either take a string or an object value.

• A string value specifies the default keyboard shortcut that should be used across allplatforms.

• An object value allows the extension developer to customize the keyboard shortcut for eachplatform. When providing platform-specific shortcuts, valid object properties aredefault,chromeos,linux,mac, andwindows.

SeeKey combination requirements for additional details.

description

A string used to provide the user with a short description of the command's purpose. This stringappears in extension keyboard shortcut management UI. Descriptions are required for standardcommands, but are ignored forAction commands.

An extension can have many commands, but may specify at most four suggested keyboard shortcuts. Theuser can manually add more shortcuts from thechrome://extensions/shortcuts dialog.

Supported Keys

The following keys are usable command shortcuts. Key definitions are case sensitive. Attempting toload an extension with an incorrectly cased key will result in a manifest parse error atinstallation time.

Alpha keys

A …Z

Numeric keys

0 …9

Standard key strings

General–Comma,Period,Home,End,PageUp,PageDown,Space,Insert,Delete

Arrow keys–Up,Down,Left,Right

Media Keys–MediaNextTrack,MediaPlayPause,MediaPrevTrack,MediaStop

Modifier key strings

Ctrl,Alt,Shift,MacCtrl (macOS only),Command (macOS only),Search (ChromeOS only)

Key combination requirements

• Extension command shortcuts must include eitherCtrl orAlt.

  • Modifierscannot be used in combination with Media Keys.

  • On many macOS keyboards,Alt refers to the Option key.

  • On macOS,Command orMacCtrl can also be used in place ofCtrl orAlt (see next bullet point).

• On macOSCtrl is automatically converted intoCommand.

  • Command can also be used in the"mac" shortcut to explicitly refer to the Command key.

  • To use the Control key on macOS, replaceCtrl withMacCtrl when defining the"mac"shortcut.

  • UsingMacCtrl in the combination for another platform will cause a validation error and prevent the extension from being installed.

• Shift is an optional modifier on all platforms.

• Search is an optional modifier exclusive to ChromeOS.

• Certain operating system and Chrome shortcuts (e.g. window management) always take priority overExtension command shortcuts and cannot be overridden.

{"name":"My extension",..."commands":{"run-foo":{"suggested_key":{"default":"Ctrl+Shift+Y","mac":"Command+Shift+Y"},"description":"Run \"foo\" on the current page."},"_execute_action":{"suggested_key":{"windows":"Ctrl+Shift+Y","mac":"Command+Shift+Y","chromeos":"Ctrl+Shift+U","linux":"Ctrl+Shift+J"}}},...}

chrome.commands.onCommand.addListener((command)=>{console.log(`Command:${command}`);});

The_execute_action (Manifest V3),_execute_browser_action (Manifest V2), and_execute_page_action (Manifest V2) commands are reserved for the action of trigger your action,browser action, or page action respectively. These commands don't dispatchcommand.onCommand events like standard commands.

If you need to take action based on your popup opening, consider listening for aDOMContentLoaded event inside your popup's JavaScript.

Scope

By default, commands are scoped to the Chrome browser. This means that when the browser does nothave focus, command shortcuts are inactive. Beginning in Chrome 35, extension developers canoptionally mark a command as "global". Global commands also work while Chromedoes not have focus.

{"name":"My extension",..."commands":{"toggle-feature-foo":{"suggested_key":{"default":"Ctrl+Shift+5"},"description":"Toggle feature foo","global":true}},...}

{"name":"Command demo - basic","version":"1.0","manifest_version":3,"background":{"service_worker":"service-worker.js"},"commands":{"inject-script":{"suggested_key":"Ctrl+Shift+Y","description":"Inject a script on the page"}}}

chrome.commands.onCommand.addListener((command)=>{console.log(`Command "${command}" triggered`);});

As described in theConcepts and usage section, you can also map a command to an extension'saction. The following example injects a content script that shows analert on the current page when the user either clicks the extension's action or triggers thekeyboard shortcut.

manifest.json:

{"name":"Commands demo - action invocation","version":"1.0","manifest_version":3,"background":{"service_worker":"service-worker.js"},"permissions":["activeTab","scripting"],"action":{},"commands":{"_execute_action":{"suggested_key":{"default":"Ctrl+U","mac":"Command+U"}}}}

service-worker.js:

chrome.action.onClicked.addListener((tab)=>{chrome.scripting.executeScript({target:{tabId:tab.id},func:contentScriptFunc,args:['action'],});});functioncontentScriptFunc(name){alert(`"${name}" executed`);}// This callback WILL NOT be called for "_execute_action"chrome.commands.onCommand.addListener((command)=>{console.log(`Command "${command}" called`);});

Verify commands registered

If an extension attempts to register a shortcut that is already used by another extension, thesecond extension's shortcut won't register as expected. You can provide a more robust end userexperience by anticipating this possibility and checking for collisions at install time.

service-worker.js:

chrome.runtime.onInstalled.addListener((details)=>{if(details.reason===chrome.runtime.OnInstalledReason.INSTALL){checkCommandShortcuts();}});// Only use this function during the initial install phase. After// installation the user may have intentionally unassigned commands.functioncheckCommandShortcuts(){chrome.commands.getAll((commands)=>{letmissingShortcuts=[];for(let{name,shortcut}ofcommands){if(shortcut===''){missingShortcuts.push(name);}}if(missingShortcuts.length >0){// Update the extension UI to inform the user that one or more// commands are currently unassigned.}});}

chrome.commands.getAll(
  callback?: function,
)

chrome.commands.onCommand.addListener(
  callback: function,
)