Description

Manifest

Concepts and usage

The Commands API allows extension developers to define specific commands, andbind them to a default key combination. Each command an extension accepts mustbe declared as properties of the"commands" object in theextension'smanifest.

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

suggested_key

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

• A string value specifies the default keyboard shortcut that should beused across all platforms.

  • An object value allows the extension developer to customize thekeyboard shortcut for each platform. When providing platform-specificshortcuts, 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'spurpose. This string appears in extension keyboard shortcut management UI.Descriptions are required for standard commands, but are ignored forActioncommands.

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

Supported Keys

The following keys are usable command shortcuts. Key definitions are casesensitive. Attempting to load an extension with an incorrectly cased key willresult in a manifest parse error at installation 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),Option (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,and theOption key can be used in place ofAlt (see next bulletpoint).

• On macOSCtrl is automatically converted intoCommand.

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

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

  • UsingMacCtrl in the combination for another platform will cause avalidation 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 over Extension command shortcuts and cannot beoverridden.

{"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 oftrigger your action, browser action, or page action respectively. These commandsdon't dispatchcommand.onCommand events like standardcommands.

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 thebrowser does not have focus, command shortcuts are inactive. Beginning in Chrome35, extension developers can optionally mark a command as "global". Globalcommands 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 canalso map a command to an extension's action. The following example injects acontent script that shows an alert on the current page when the user eitherclicks the extension's action or triggers the keyboard 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 anotherextension, the second extension's shortcut won't register as expected. You canprovide a more robust end user experience by anticipating this possibility andchecking 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(): Promise<Command[]>

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