Commands is a generic package that allows registering and modifying commands to be displayed using the commands menu, also called the Command Palette. The Command Palette can be accessed in the Editor using cmd+k.
Types of commands
There are two ways to register commands: static or dynamic. Both methods receive a command object as an argument, which provides:
name: A unique machine-readable name for the commandlabel: A human-readable labelicon: An SVG iconcallback: A callback function that is called when the command is selectedcontext: (Optional) The context of the command
Static commands
Static commands can be registered using the wp.data.dispatch( wp.commands.store ).registerCommand action or using the wp.commands.useCommand React hook. Static commands are commonly used to perform a specific action. These could include adding a new page or opening a section of the Editor interface, such as opening the Editor Preferences modal. See the useCommand code example below.
Dynamic commands
Dynamic commands, on the other hand, are registered using “command loaders”, wp.commands.useCommandLoader. These loaders are needed when the command list depends on a search term entered by the user in the Command Palette input or when some commands are only available when some conditions are met.
For example, when a user types “contact”, the Command Palette needs to filter the available pages using that input to try and find the Contact page. See the useCommandLoader code example below.
Contextual commands
Static and dynamic commands can be contextual. This means that in a given context (for example, when navigating the Site Editor or editing a template), some specific commands are given more priority and are visible as soon as you open the Command Palette. Also, when typing the Command Palette, these contextual commands are shown above the rest of the commands.
At the moment, three contexts have been implemented:
site-editor: This is the context that is set when you are navigating in the site editor (sidebar visible).entity-edit: This is the context that is set when you are editing a document (template, template part or page).block-selection-edit: This is the context that is set when a block is selected.
As the usage of the Command Palette expands, more contexts will be added.
Attaching a command or command loader to a given context is as simple as adding the context property (with the right context value from the available contexts above) to the useCommand or useCommandLoader calls.
WordPress Data API
The Command Palette also offers a number of selectors and actions to manipulate its state, which include:
- Retrieving the registered commands and command loaders using the following selectors
getCommandsandgetCommandLoader - Checking if the Command Palette is open using the
isOpenselector. - Programmatically open or close the Command Palette using the
openandcloseactions.
See the Commands Data documentation for more information.
Installation
Install the module
npm install @wordpress/commands --save
This package assumes that your code will run in an ES2015+ environment. If you’re using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.
API
store
Store definition for the commands namespace.
Related
Usage
import { store as commandsStore } from '@wordpress/commands';
import { useDispatch } from '@wordpress/data';
...
const { open: openCommandCenter } = useDispatch( commandsStore );
Type
Object
useCommand
Attach a command to the command palette. Used for static commands.
Usage
import { useCommand } from '@wordpress/commands';
import { plus } from '@wordpress/icons';
useCommand( {
name: 'myplugin/my-command-name',
label: __( 'Add new post' ),
icon: plus,
callback: ( { close } ) => {
document.location.href = 'post-new.php';
close();
},
} );
Parameters
- command
import('../store/actions').WPCommandConfig: command config.
useCommandLoader
Attach a command loader to the command palette. Used for dynamic commands.
Usage
import { useCommandLoader } from '@wordpress/commands';
import { post, page, layout, symbolFilled } from '@wordpress/icons';
const icons = {
post,
page,
wp_template: layout,
wp_template_part: symbolFilled,
};
function usePageSearchCommandLoader( { search } ) {
// Retrieve the pages for the "search" term.
const { records, isLoading } = useSelect( ( select ) => {
const { getEntityRecords } = select( coreStore );
const query = {
search: !! search ? search : undefined,
per_page: 10,
orderby: search ? 'relevance' : 'date',
};
return {
records: getEntityRecords( 'postType', 'page', query ),
isLoading: ! select( coreStore ).hasFinishedResolution(
'getEntityRecords',
'postType', 'page', query ]
),
};
}, [ search ] );
// Create the commands.
const commands = useMemo( () => {
return ( records ?? [] ).slice( 0, 10 ).map( ( record ) => {
return {
name: record.title?.rendered + ' ' + record.id,
label: record.title?.rendered
? record.title?.rendered
: __( '(no title)' ),
icon: icons[ postType ],
callback: ( { close } ) => {
const args = {
postType,
postId: record.id,
...extraArgs,
};
document.location = addQueryArgs( 'site-editor.php', args );
close();
},
};
} );
}, [ records, history ] );
return {
commands,
isLoading,
};
}
useCommandLoader( {
name: 'myplugin/page-search',
hook: usePageSearchCommandLoader,
} );
Parameters
- loader
import('../store/actions').WPCommandLoaderConfig: command loader config.
Contributing to this package
This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.
To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main contributor guide.