@wordpress/commands

Commands

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 command
• label: A human-readable label
• icon: An SVG icon
• callback: A callback function that is called when the command is selected
• context: (Optional) The context of the command
• keywords: (Optional) An array of keywords for search matching

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 getCommands and getCommandLoader
• Checking if the Command Palette is open using the isOpen selector.
• Programmatically open or close the Command Palette using the open and close actions.

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.

This package requires the following stylesheets to be included for proper styling:

/* From node_modules: */
@import '@wordpress/components/build-style/style.css';
@import '@wordpress/commands/build-style/style.css';

API

store

Store definition for the commands namespace.

Related

• https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore

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.

useCommands

Attach multiple commands to the command palette. Used for static commands.

Usage

import { useCommands } from '@wordpress/commands';
import { plus, edit } from '@wordpress/icons';

useCommands( [
	{
		name: 'myplugin/add-post',
		label: __( 'Add new post' ),
		icon: plus,
		callback: ( { close } ) => {
			document.location.href = 'post-new.php';
			close();
		},
	},
	{
		name: 'myplugin/edit-posts',
		label: __( 'Edit posts' ),
		icon: edit,
		callback: ( { close } ) => {
			document.location.href = 'edit.php';
			close();
		},
	},
] );

Parameters

• commands import('../store/actions').WPCommandConfig[]: Array of command configs.

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.