Namespace: core/block-editor.

Selectors

areInnerBlocksControlled

Checks if a given block has controlled inner blocks.

Parameters

• state Object: Global application state.
• clientId string: The block to check.

Returns

• boolean: True if the block has controlled inner blocks.

canEditBlock

Determines if the given block is allowed to be edited.

Parameters

• state Object: Editor state.
• clientId string: The block client Id.

Returns

• boolean: Whether the given block is allowed to be edited.

canInsertBlocks

Determines if the given blocks are allowed to be inserted into the block list.

Parameters

• state Object: Editor state.
• clientIds string[]: The block client IDs to be inserted.
• rootClientId ?string: Optional root client ID of block list.

Returns

• boolean: Whether the given blocks are allowed to be inserted.

canInsertBlockType

Determines if the given block type is allowed to be inserted into the block list.

Parameters

• state Object: Editor state.
• blockName string: The name of the block type, e.g.’ core/paragraph’.
• rootClientId ?string: Optional root client ID of block list.

Returns

• boolean: Whether the given block type is allowed to be inserted.

canLockBlockType

Determines if the given block type can be locked/unlocked by a user.

Parameters

• state Object: Editor state.
• nameOrType (string|Object): Block name or type object.

Returns

• boolean: Whether a given block type can be locked/unlocked.

canMoveBlock

Determines if the given block is allowed to be moved.

Parameters

• state Object: Editor state.
• clientId string: The block client Id.

Returns

• boolean: Whether the given block is allowed to be moved.

canMoveBlocks

Determines if the given blocks are allowed to be moved.

Parameters

• state Object: Editor state.
• clientIds string: The block client IDs to be moved.

Returns

• boolean: Whether the given blocks are allowed to be moved.

canRemoveBlock

Determines if the given block is allowed to be deleted.

Parameters

• state Object: Editor state.
• clientId string: The block client Id.

Returns

• boolean: Whether the given block is allowed to be removed.

canRemoveBlocks

Determines if the given blocks are allowed to be removed.

Parameters

• state Object: Editor state.
• clientIds string: The block client IDs to be removed.

Returns

• boolean: Whether the given blocks are allowed to be removed.

didAutomaticChange

Returns true if the last change was an automatic change, false otherwise.

Parameters

• state Object: Global application state.

Returns

• boolean: Whether the last change was automatic.

getAdjacentBlockClientId

Returns the client ID of the block adjacent one at the given reference startClientId and modifier directionality. Defaults start startClientId to the selected block, and direction as next block. Returns null if there is no adjacent block.

Parameters

• state Object: Editor state.
• startClientId ?string: Optional client ID of block from which to search.
• modifier ?number: Directionality multiplier (1 next, -1 previous).

Returns

• ?string: Return the client ID of the block, or null if none exists.

getAllowedBlocks

Returns the list of allowed inserter blocks for inner blocks children.

Parameters

• state Object: Editor state.
• rootClientId ?string: Optional root client ID of block list.

Returns

• Array?: The list of allowed block types.

getBlock

Returns a block given its client ID. This is a parsed copy of the block, containing its blockName, clientId, and current attributes state. This is not the block’s registration settings, which must be retrieved from the blocks module registration store.

getBlock recurses through its inner blocks until all its children blocks have been retrieved. Note that getBlock will not return the child inner blocks of an inner block controller. This is because an inner block controller syncs itself with its own entity, and should therefore not be included with the blocks of a different entity. For example, say you call getBlocks( TP ) to get the blocks of a template part. If another template part is a child of TP, then the nested template part’s child blocks will not be returned. This way, the template block itself is considered part of the parent, but the children are not.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.

Returns

• Object: Parsed block object.

getBlockAttributes

Returns a block’s attributes given its client ID, or null if no block exists with the client ID.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.

Returns

• ?Object: Block attributes.

getBlockCount

Returns the number of blocks currently present in the post.

Parameters

• state Object: Editor state.
• rootClientId ?string: Optional root client ID of block list.

Returns

• number: Number of blocks in the post.

getBlockEditingMode

Returns the block editing mode for a given block.

The mode can be one of three options:

• 'disabled': Prevents editing the block entirely, i.e. it cannot be selected.
• 'contentOnly': Hides all non-content UI, e.g. auxiliary controls in the toolbar, the block movers, block settings.
• 'default': Allows editing the block as normal.

Blocks can set a mode using the useBlockEditingMode hook.

The mode is inherited by all of the block’s inner blocks, unless they have their own mode.

A template lock can also set a mode. If the template lock is 'contentOnly', the block’s mode is overridden to 'contentOnly' if the block has a content role attribute, or 'disabled' otherwise.

Related

• useBlockEditingMode

Parameters

• state Object: Global application state.
• clientId string: The block client ID, or '' for the root container.

Returns

• BlockEditingMode: The block editing mode. One of 'disabled', 'contentOnly', or 'default'.

getBlockHierarchyRootClientId

Given a block client ID, returns the root of the hierarchy from which the block is nested, return the block itself for root level blocks.

Parameters

• state Object: Editor state.
• clientId string: Block from which to find root client ID.

Returns

• string: Root client ID

getBlockIndex

Returns the index at which the block corresponding to the specified client ID occurs within the block order, or -1 if the block does not exist.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.

Returns

• number: Index at which block exists in order.

getBlockInsertionPoint

Returns the location of the insertion cue. Defaults to the last index.

Parameters

• state Object: Editor state.

Returns

• Object: Insertion point object with rootClientId, index.

getBlockListSettings

Returns the Block List settings of a block, if any exist.

Parameters

• state Object: Editor state.
• clientId ?string: Block client ID.

Returns

• ?Object: Block settings of the block if set.

getBlockMode

Returns the block’s editing mode, defaulting to “visual” if not explicitly assigned.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.

Returns

• Object: Block editing mode.

getBlockName

Returns a block’s name given its client ID, or null if no block exists with the client ID.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.

Returns

• string: Block name.

getBlockNamesByClientId

Given an array of block client IDs, returns the corresponding array of block names.

Parameters

• state Object: Editor state.
• clientIds string[]: Client IDs for which block names are to be returned.

Returns

• string[]: Block names.

getBlockOrder

Returns an array containing all block client IDs in the editor in the order they appear. Optionally accepts a root client ID of the block list for which the order should be returned, defaulting to the top-level block order.

Parameters

• state Object: Editor state.
• rootClientId ?string: Optional root client ID of block list.

Returns

• Array: Ordered client IDs of editor blocks.

getBlockParents

Given a block client ID, returns the list of all its parents from top to bottom.

Parameters

• state Object: Editor state.
• clientId string: Block from which to find root client ID.
• ascending boolean: Order results from bottom to top (true) or top to bottom (false).

Returns

• Array: ClientIDs of the parent blocks.

getBlockParentsByBlockName

Given a block client ID and a block name, returns the list of all its parents from top to bottom, filtered by the given name(s). For example, if passed ‘core/group’ as the blockName, it will only return parents which are group blocks. If passed [ 'core/group', 'core/cover'], as the blockName, it will return parents which are group blocks and parents which are cover blocks.

Parameters

• state Object: Editor state.
• clientId string: Block from which to find root client ID.
• blockName string|string[]: Block name(s) to filter.
• ascending boolean: Order results from bottom to top (true) or top to bottom (false).

Returns

• Array: ClientIDs of the parent blocks.

getBlockRootClientId

Given a block client ID, returns the root block from which the block is nested, an empty string for top-level blocks, or null if the block does not exist.

Parameters

• state Object: Editor state.
• clientId string: Block from which to find root client ID.

Returns

• ?string: Root client ID, if exists

getBlocks

Returns all block objects for the current post being edited as an array in the order they appear in the post. Note that this will exclude child blocks of nested inner block controllers.

Parameters

• state Object: Editor state.
• rootClientId ?string: Optional root client ID of block list.

Returns

• Object[]: Post blocks.

getBlocksByClientId

Given an array of block client IDs, returns the corresponding array of block objects.

Parameters

• state Object: Editor state.
• clientIds string[]: Client IDs for which blocks are to be returned.

Returns

• WPBlock[]: Block objects.

getBlocksByName

Returns all blocks that match a blockName. Results include nested blocks.

Parameters

• state Object: Global application state.
• blockName string[]: Block name(s) for which clientIds are to be returned.

Returns

• Array: Array of clientIds of blocks with name equal to blockName.

getBlockSelectionEnd

Returns the current block selection end. This value may be null, and it may represent either a singular block selection or multi-selection end. A selection is singular if its start and end match.

Parameters

• state Object: Global application state.

Returns

• ?string: Client ID of block selection end.

getBlockSelectionStart

Returns the current block selection start. This value may be null, and it may represent either a singular block selection or multi-selection start. A selection is singular if its start and end match.

Parameters

• state Object: Global application state.

Returns

• ?string: Client ID of block selection start.

getBlockTransformItems

Determines the items that appear in the available block transforms list.

Each item object contains what’s necessary to display a menu item in the transform list and handle its selection.

The ‘frecency’ property is a heuristic (https://en.wikipedia.org/wiki/Frecency) that combines block usage frequency and recency.

Items are returned ordered descendingly by their ‘frecency’.

Parameters

• state Object: Editor state.
• blocks Object|Object[]: Block object or array objects.
• rootClientId ?string: Optional root client ID of block list.

Returns

• WPEditorTransformItem[]: Items that appear in inserter.

Type Definition

• WPEditorTransformItem Object

Properties

• id string: Unique identifier for the item.
• name string: The type of block to create.
• title string: Title of the item, as it appears in the inserter.
• icon string: Dashicon for the item, as it appears in the inserter.
• isDisabled boolean: Whether or not the user should be prevented from inserting this item.
• frecency number: Heuristic that combines frequency and recency.

getClientIdsOfDescendants

Returns an array containing the clientIds of all descendants of the blocks given. Returned ids are ordered first by the order of the ids given, then by the order that they appear in the editor.

Parameters

• state Object: Global application state.
• rootIds string|string[]: Client ID(s) for which descendant blocks are to be returned.

Returns

• Array: Client IDs of descendants.

getClientIdsWithDescendants

Returns an array containing the clientIds of the top-level blocks and their descendants of any depth (for nested blocks). Ids are returned in the same order that they appear in the editor.

Parameters

• state Object: Global application state.

Returns

• Array: ids of top-level and descendant blocks.

getDirectInsertBlock

Returns the block to be directly inserted by the block appender.

Parameters

• state Object: Editor state.
• rootClientId ?string: Optional root client ID of block list.

Returns

• WPDirectInsertBlock|undefined: The block type to be directly inserted.

Type Definition

• WPDirectInsertBlock Object

Properties

• name string: The type of block.
• attributes ?Object: Attributes to pass to the newly created block.
• attributesToCopy ?Array<string>: Attributes to be copied from adjacent blocks when inserted.

getDraggedBlockClientIds

Returns the client ids of any blocks being directly dragged.

This does not include children of a parent being dragged.

Parameters

• state Object: Global application state.

Returns

• string[]: Array of dragged block client ids.

getFirstMultiSelectedBlockClientId

Returns the client ID of the first block in the multi-selection set, or null if there is no multi-selection.

Parameters

• state Object: Editor state.

Returns

• ?string: First block client ID in the multi-selection set.

getGlobalBlockCount

Returns the total number of blocks, or the total number of blocks with a specific name in a post. The number returned includes nested blocks.

Parameters

• state Object: Global application state.
• blockName ?string: Optional block name, if specified only blocks of that type will be counted.

Returns

• number: Number of blocks in the post, or number of blocks with name equal to blockName.

getHoveredBlockClientId

Deprecated

Returns the currently hovered block.

getInserterItems

Determines the items that appear in the inserter. Includes both static items (e.g. a regular block type) and dynamic items (e.g. a reusable block).

Each item object contains what’s necessary to display a button in the inserter and handle its selection.

The ‘frecency’ property is a heuristic (https://en.wikipedia.org/wiki/Frecency) that combines block usage frequency and recency.

Items are returned ordered descendingly by their ‘utility’ and ‘frecency’.

Parameters

• state Object: Editor state.
• rootClientId ?string: Optional root client ID of block list.

Returns

• WPEditorInserterItem[]: Items that appear in inserter.

Type Definition

• WPEditorInserterItem Object

Properties

• id string: Unique identifier for the item.
• name string: The type of block to create.
• initialAttributes Object: Attributes to pass to the newly created block.
• title string: Title of the item, as it appears in the inserter.
• icon string: Dashicon for the item, as it appears in the inserter.
• category string: Block category that the item is associated with.
• keywords string[]: Keywords that can be searched to find this item.
• isDisabled boolean: Whether or not the user should be prevented from inserting this item.
• frecency number: Heuristic that combines frequency and recency.

getLastMultiSelectedBlockClientId

Returns the client ID of the last block in the multi-selection set, or null if there is no multi-selection.

Parameters

• state Object: Editor state.

Returns

• ?string: Last block client ID in the multi-selection set.

getLowestCommonAncestorWithSelectedBlock

Given a block client ID, returns the lowest common ancestor with selected client ID.

Parameters

• state Object: Editor state.
• clientId string: Block from which to find common ancestor client ID.

Returns

• string: Common ancestor client ID or undefined

getMultiSelectedBlockClientIds

Returns the current multi-selection set of block client IDs, or an empty array if there is no multi-selection.

Parameters

• state Object: Editor state.

Returns

• Array: Multi-selected block client IDs.

getMultiSelectedBlocks

Returns the current multi-selection set of blocks, or an empty array if there is no multi-selection.

Parameters

• state Object: Editor state.

Returns

• Array: Multi-selected block objects.

getMultiSelectedBlocksEndClientId

Returns the client ID of the block which ends the multi-selection set, or null if there is no multi-selection.

This is not necessarily the last client ID in the selection.

Related

• getLastMultiSelectedBlockClientId

Parameters

• state Object: Editor state.

Returns

• ?string: Client ID of block ending multi-selection.

getMultiSelectedBlocksStartClientId

Returns the client ID of the block which begins the multi-selection set, or null if there is no multi-selection.

This is not necessarily the first client ID in the selection.

Related

• getFirstMultiSelectedBlockClientId

Parameters

• state Object: Editor state.

Returns

• ?string: Client ID of block beginning multi-selection.

getNextBlockClientId

Returns the next block’s client ID from the given reference start ID. Defaults start to the selected block. Returns null if there is no next block.

Parameters

• state Object: Editor state.
• startClientId ?string: Optional client ID of block from which to search.

Returns

• ?string: Adjacent block’s client ID, or null if none exists.

getPatternsByBlockTypes

Returns the list of patterns based on their declared blockTypes and a block’s name. Patterns can use blockTypes to integrate in work flows like suggesting appropriate patterns in a Placeholder state(during insertion) or blocks transformations.

Parameters

• state Object: Editor state.
• blockNames string|string[]: Block’s name or array of block names to find matching patterns.
• rootClientId ?string: Optional target root client ID.

Returns

• Array: The list of matched block patterns based on declared blockTypes and block name.

getPreviousBlockClientId

Returns the previous block’s client ID from the given reference start ID. Defaults start to the selected block. Returns null if there is no previous block.

Parameters

• state Object: Editor state.
• startClientId ?string: Optional client ID of block from which to search.

Returns

• ?string: Adjacent block’s client ID, or null if none exists.

getSelectedBlock

Returns the currently selected block, or null if there is no selected block.

Usage

import { select } from '@wordpress/data';
import { store as blockEditorStore } from '@wordpress/block-editor';

// Set initial active block client ID
let activeBlockClientId = null;

const getActiveBlockData = () => {
    const activeBlock = select( blockEditorStore ).getSelectedBlock();

    if ( activeBlock && activeBlock.clientId !== activeBlockClientId ) {
        activeBlockClientId = activeBlock.clientId;

        // Get active block name and attributes
        const activeBlockName = activeBlock.name;
        const activeBlockAttributes = activeBlock.attributes;

        // Log active block name and attributes
        console.log( activeBlockName, activeBlockAttributes );
    }
};

// Subscribe to changes in the editor
// wp.data.subscribe(() => {
// getActiveBlockData()
// })

// Update active block data on click
// onclick="getActiveBlockData()"

Parameters

• state Object: Global application state.

Returns

• ?Object: Selected block.

getSelectedBlockClientId

Returns the currently selected block client ID, or null if there is no selected block.

Parameters

• state Object: Editor state.

Returns

• ?string: Selected block client ID.

getSelectedBlockClientIds

Returns the current selection set of block client IDs (multiselection or single selection).

Parameters

• state Object: Editor state.

Returns

• Array: Multi-selected block client IDs.

getSelectedBlockCount

Returns the number of blocks currently selected in the post.

Parameters

• state Object: Global application state.

Returns

• number: Number of blocks selected in the post.

getSelectedBlocksInitialCaretPosition

Returns the initial caret position for the selected block. This position is to used to position the caret properly when the selected block changes. If the current block is not a RichText, having initial position set to 0 means “focus block”

Parameters

• state Object: Global application state.

Returns

• 0|-1|null: Initial position.

getSelectionEnd

Returns the current selection end block client ID, attribute key and text offset.

Parameters

• state Object: Block editor state.

Returns

• WPBlockSelection: Selection end information.

getSelectionStart

Returns the current selection start block client ID, attribute key and text offset.

Parameters

• state Object: Block editor state.

Returns

• WPBlockSelection: Selection start information.

getSettings

Returns the editor settings.

Parameters

• state Object: Editor state.

Returns

• Object: The editor settings object.

getTemplate

Returns the defined block template

Parameters

• state boolean:

Returns

• ?Array: Block Template.

getTemplateLock

Returns the defined block template lock. Optionally accepts a root block client ID as context, otherwise defaulting to the global context.

Parameters

• state Object: Editor state.
• rootClientId ?string: Optional block root client ID.

Returns

• string|false: Block Template Lock

hasBlockMovingClientId

Deprecated

Returns whether block moving mode is enabled.

hasDraggedInnerBlock

Returns true if one of the block’s inner blocks is dragged.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.
• deep boolean: Perform a deep check.

Returns

• boolean: Whether the block has an inner block dragged

hasInserterItems

Determines whether there are items to show in the inserter.

Parameters

• state Object: Editor state.
• rootClientId ?string: Optional root client ID of block list.

Returns

• boolean: Items that appear in inserter.

hasMultiSelection

Returns true if a multi-selection has been made, or false otherwise.

Parameters

• state Object: Editor state.

Returns

• boolean: Whether multi-selection has been made.

hasSelectedBlock

Returns true if there is a single selected block, or false otherwise.

Parameters

• state Object: Editor state.

Returns

• boolean: Whether a single block is selected.

hasSelectedInnerBlock

Returns true if one of the block’s inner blocks is selected.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.
• deep boolean: Perform a deep check.

Returns

• boolean: Whether the block has an inner block selected

isAncestorBeingDragged

Returns whether a parent/ancestor of the block is being dragged.

Parameters

• state Object: Global application state.
• clientId string: Client id for block to check.

Returns

• boolean: Whether the block’s ancestor is being dragged.

isAncestorMultiSelected

Returns true if an ancestor of the block is multi-selected, or false otherwise.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.

Returns

• boolean: Whether an ancestor of the block is in multi-selection set.

isBlockBeingDragged

Returns whether the block is being dragged.

Only returns true if the block is being directly dragged, not if the block is a child of a parent being dragged. See isAncestorBeingDragged for child blocks.

Parameters

• state Object: Global application state.
• clientId string: Client id for block to check.

Returns

• boolean: Whether the block is being dragged.

isBlockHighlighted

Returns true if the current highlighted block matches the block clientId.

Parameters

• state Object: Global application state.
• clientId string: The block to check.

Returns

• boolean: Whether the block is currently highlighted.

isBlockInsertionPointVisible

Returns true if the block insertion point is visible.

Parameters

• state Object: Global application state.

Returns

• ?boolean: Whether the insertion point is visible or not.

isBlockMultiSelected

Returns true if the client ID occurs within the block multi-selection, or false otherwise.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.

Returns

• boolean: Whether block is in multi-selection set.

isBlockSelected

Returns true if the block corresponding to the specified client ID is currently selected and no multi-selection exists, or false otherwise.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.

Returns

• boolean: Whether block is selected and multi-selection exists.

isBlockValid

Returns whether a block is valid or not.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.

Returns

• boolean: Is Valid.

isBlockVisible

Tells if the block is visible on the canvas or not.

Parameters

• state Object: Global application state.
• clientId Object: Client Id of the block.

Returns

• boolean: True if the block is visible.

isBlockWithinSelection

Returns true if the block corresponding to the specified client ID is currently selected but isn’t the last of the selected blocks. Here “last” refers to the block sequence in the document, not the sequence of multi-selection, which is why state.selectionEnd isn’t used.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.

Returns

• boolean: Whether block is selected and not the last in the selection.

isCaretWithinFormattedText

Deprecated

Returns true if the caret is within formatted text, or false otherwise.

Returns

• boolean: Whether the caret is within formatted text.

isDraggingBlocks

Returns true if the user is dragging blocks, or false otherwise.

Parameters

• state Object: Global application state.

Returns

• boolean: Whether user is dragging blocks.

isFirstMultiSelectedBlock

Returns true if a multi-selection exists, and the block corresponding to the specified client ID is the first block of the multi-selection set, or false otherwise.

Parameters

• state Object: Editor state.
• clientId string: Block client ID.

Returns

• boolean: Whether block is first in multi-selection.

isGroupable

Indicates if the provided blocks(by client ids) are groupable. We need to have at least one block, have a grouping block name set and be able to remove these blocks.

Parameters

• state Object: Global application state.
• clientIds string[]: Block client ids. If not passed the selected blocks client ids will be used.

Returns

• boolean: True if the blocks are groupable.

isLastBlockChangePersistent

Returns true if the most recent block change is be considered persistent, or false otherwise. A persistent change is one committed by BlockEditorProvider via its onChange callback, in addition to onInput.

Parameters

• state Object: Block editor state.

Returns

• boolean: Whether the most recent block change was persistent.

isMultiSelecting

Whether in the process of multi-selecting or not. This flag is only true while the multi-selection is being selected (by mouse move), and is false once the multi-selection has been settled.

Related

• hasMultiSelection

Parameters

• state Object: Global application state.

Returns

• boolean: True if multi-selecting, false if not.

isSelectionEnabled

Selector that returns if multi-selection is enabled or not.

Parameters

• state Object: Global application state.

Returns

• boolean: True if it should be possible to multi-select blocks, false if multi-selection is disabled.

isTyping

Returns true if the user is typing, or false otherwise.

Parameters

• state Object: Global application state.

Returns

• boolean: Whether user is typing.

isUngroupable

Indicates if a block is ungroupable. A block is ungroupable if it is a single grouping block with inner blocks. If a block has an ungroup transform, it is also ungroupable, without the requirement of being the default grouping block. Additionally a block can only be ungrouped if it has inner blocks and can be removed. Section blocks are not ungroupable.

Parameters

• state Object: Global application state.
• clientId string: Client Id of the block. If not passed the selected block’s client id will be used.

Returns

• boolean: True if the block is ungroupable.

isValidTemplate

Returns whether the blocks matches the template or not.

Parameters

• state boolean:

Returns

• ?boolean: Whether the template is valid or not.

wasBlockJustInserted

Tells if the block with the passed clientId was just inserted.

Parameters

• state Object: Global application state.
• clientId Object: Client Id of the block.
• source ?string: Optional insertion source of the block.

Returns

• boolean: True if the block matches the last block inserted from the specified source.

Actions

clearSelectedBlock

Action that clears the block selection.

Returns

• Object: Action object.

duplicateBlocks

Action that duplicates a list of blocks.

Parameters

• clientIds string[]:
• updateSelection boolean:

enterFormattedText

Deprecated

Returns an action object used in signalling that the caret has entered formatted text.

Returns

• Object: Action object.

exitFormattedText

Deprecated

Returns an action object used in signalling that the user caret has exited formatted text.

Returns

• Object: Action object.

flashBlock

Action that “flashes” the block with a given clientId by rhythmically highlighting it.

Parameters

• clientId string: Target block client ID.
• timeout number: Duration in milliseconds to keep the highlight. Defaults to 150ms.

hideInsertionPoint

Action that hides the insertion point.

hoverBlock

Deprecated

Returns an action object used in signalling that the block with the specified client ID has been hovered.

insertAfterBlock

Action that inserts a default block after a given block.

Parameters

• clientId string:

insertBeforeBlock

Action that inserts a default block before a given block.

Parameters

• clientId string:

insertBlock

Action that inserts a single block, optionally at a specific index respective a root block list.

Only allowed blocks are inserted. The action may fail silently for blocks that are not allowed or if a templateLock is active on the block list.

Parameters

• block Object: Block object to insert.
• index ?number: Index at which block should be inserted.
• rootClientId ?string: Optional root client ID of block list on which to insert.
• updateSelection ?boolean: If true block selection will be updated. If false, block selection will not change. Defaults to true.
• initialPosition 0|-1|null: Initial focus position. Setting it to null prevent focusing the inserted block.
• meta ?Object: Optional Meta values to be passed to the action object.

Returns

• Object: Action object.

insertBlocks

Action that inserts an array of blocks, optionally at a specific index respective a root block list.

Only allowed blocks are inserted. The action may fail silently for blocks that are not allowed or if a templateLock is active on the block list.

Parameters

• blocks Object[]: Block objects to insert.
• index ?number: Index at which block should be inserted.
• rootClientId ?string: Optional root client ID of block list on which to insert.
• updateSelection ?boolean: If true block selection will be updated. If false, block selection will not change. Defaults to true.
• initialPosition 0|-1|null: Initial focus position. Setting it to null prevent focusing the inserted block.
• meta ?Object: Optional Meta values to be passed to the action object.

Returns

• Object: Action object.

insertDefaultBlock

Action that adds a new block of the default type to the block list.

Parameters

• attributes ?Object: Optional attributes of the block to assign.
• rootClientId ?string: Optional root client ID of block list on which to append.
• index ?number: Optional index where to insert the default block.

mergeBlocks

Action that merges two blocks.

Parameters

• firstBlockClientId string: Client ID of the first block to merge.
• secondBlockClientId string: Client ID of the second block to merge.

moveBlocksDown

Undocumented declaration.

moveBlocksToPosition

Action that moves given blocks to a new position.

Parameters

• clientIds ?string: The client IDs of the blocks.
• fromRootClientId ?string: Root client ID source.
• toRootClientId ?string: Root client ID destination.
• index number: The index to move the blocks to.

moveBlocksUp

Undocumented declaration.

moveBlockToPosition

Action that moves given block to a new position.

Parameters

• clientId ?string: The client ID of the block.
• fromRootClientId ?string: Root client ID source.
• toRootClientId ?string: Root client ID destination.
• index number: The index to move the block to.

multiSelect

Action that changes block multi-selection.

Parameters

• start string: First block of the multi selection.
• end string: Last block of the multiselection.
• __experimentalInitialPosition number|null: Optional initial position. Pass as null to skip focus within editor canvas.

receiveBlocks

Deprecated

Returns an action object used in signalling that blocks have been received. Unlike resetBlocks, these should be appended to the existing known set, not replacing.

Parameters

• blocks Object[]: Array of block objects.

Returns

• Object: Action object.

registerInserterMediaCategory

Registers a new inserter media category. Once registered, the media category is available in the inserter’s media tab.

The following interfaces are used:

Type Definition

• InserterMediaRequest Object: Interface for inserter media requests.

Properties

• per_page number: How many items to fetch per page.
• search string: The search term to use for filtering the results.

Type Definition

• InserterMediaItem Object: Interface for inserter media responses. Any media resource should map their response to this interface, in order to create the core WordPress media blocks (image, video, audio).

Properties

• title string: The title of the media item.
• url `string: The source url of the media item.
• previewUrl [string]: The preview source url of the media item to display in the media list.
• id [number]: The WordPress id of the media item.
• sourceId [number|string]: The id of the media item from external source.
• alt [string]: The alt text of the media item.
• caption [string]: The caption of the media item.

Usage

wp.data.dispatch( 'core/block-editor' ).registerInserterMediaCategory( {
    name: 'openverse',
    labels: {
        name: 'Openverse',
        search_items: 'Search Openverse',
    },
    mediaType: 'image',
    async fetch( query = {} ) {
        const defaultArgs = {
            mature: false,
            excluded_source: 'flickr,inaturalist,wikimedia',
            license: 'pdm,cc0',
        };
        const finalQuery = { ...query, ...defaultArgs };
        // Sometimes you might need to map the supported request params according to `InserterMediaRequest`.
        // interface. In this example the `search` query param is named `q`.
        const mapFromInserterMediaRequest = {
            per_page: 'page_size',
            search: 'q',
        };
        const url = new URL( 'https://api.openverse.org/v1/images/' );
        Object.entries( finalQuery ).forEach( ( [ key, value ] ) => {
            const queryKey = mapFromInserterMediaRequest[ key ] || key;
            url.searchParams.set( queryKey, value );
        } );
        const response = await window.fetch( url, {
            headers: {
                'User-Agent': 'WordPress/inserter-media-fetch',
            },
        } );
        const jsonResponse = await response.json();
        const results = jsonResponse.results;
        return results.map( ( result ) => ( {
            ...result,
            // If your response result includes an `id` prop that you want to access later, it should
            // be mapped to `InserterMediaItem`'s `sourceId` prop. This can be useful if you provide
            // a report URL getter.
            // Additionally you should always clear the `id` value of your response results because
            // it is used to identify WordPress media items.
            sourceId: result.id,
            id: undefined,
            caption: result.caption,
            previewUrl: result.thumbnail,
        } ) );
    },
    getReportUrl: ( { sourceId } ) =>
        `https://wordpress.org/openverse/image/${ sourceId }/report/`,
    isExternalResource: true,
} );

Parameters

• category InserterMediaCategory: The inserter media category to register.

Type Definition

• InserterMediaCategory Object: Interface for inserter media category.

Properties

• name string: The name of the media category, that should be unique among all media categories.
• labels Object: Labels for the media category.
• labels.name string: General name of the media category. It’s used in the inserter media items list.
• labels.search_items [string]: Label for searching items. Default is ‘Search Posts’ / ‘Search Pages’.
• mediaType ('image'|'audio'|'video'): The media type of the media category.
• fetch (InserterMediaRequest) => Promise<InserterMediaItem[]>: The function to fetch media items for the category.
• getReportUrl [(InserterMediaItem) => string]: If the media category supports reporting media items, this function should return the report url for the media item. It accepts the InserterMediaItem as an argument.
• isExternalResource [boolean]: If the media category is an external resource, this should be set to true. This is used to avoid making a request to the external resource when the user

removeBlock

Returns an action object used in signalling that the block with the specified client ID is to be removed.

Parameters

• clientId string: Client ID of block to remove.
• selectPrevious boolean: True if the previous block should be selected when a block is removed.

Returns

• Object: Action object.

removeBlocks

Yields action objects used in signalling that the blocks corresponding to the set of specified client IDs are to be removed.

Parameters

• clientIds string|string[]: Client IDs of blocks to remove.
• selectPrevious boolean: True if the previous block or the immediate parent (if no previous block exists) should be selected when a block is removed.

replaceBlock

Action that replaces a single block with one or more replacement blocks.

Parameters

• clientId (string|string[]): Block client ID to replace.
• block (Object|Object[]): Replacement block(s).

Returns

• Object: Action object.

replaceBlocks

Action that replaces given blocks with one or more replacement blocks.

Parameters

• clientIds (string|string[]): Block client ID(s) to replace.
• blocks (Object|Object[]): Replacement block(s).
• indexToSelect number: Index of replacement block to select.
• initialPosition 0|-1|null: Index of caret after in the selected block after the operation.
• meta ?Object: Optional Meta values to be passed to the action object.

Returns

• Object: Action object.

replaceInnerBlocks

Returns an action object used in signalling that the inner blocks with the specified client ID should be replaced.

Parameters

• rootClientId string: Client ID of the block whose InnerBlocks will re replaced.
• blocks Object[]: Block objects to insert as new InnerBlocks
• updateSelection ?boolean: If true block selection will be updated. If false, block selection will not change. Defaults to false.
• initialPosition 0|-1|null: Initial block position.

Returns

• Object: Action object.

resetBlocks

Action that resets blocks state to the specified array of blocks, taking precedence over any other content reflected as an edit in state.

Parameters

• blocks Array: Array of blocks.

resetSelection

Returns an action object used in signalling that selection state should be reset to the specified selection.

Parameters

• selectionStart WPBlockSelection: The selection start.
• selectionEnd WPBlockSelection: The selection end.
• initialPosition 0|-1|null: Initial block position.

Returns

• Object: Action object.

selectBlock

Returns an action object used in signalling that the block with the specified client ID has been selected, optionally accepting a position value reflecting its selection directionality. An initialPosition of -1 reflects a reverse selection.

Parameters

• clientId string: Block client ID.
• initialPosition 0|-1|null: Optional initial position. Pass -1 to reflect reverse selection or null to prevent focusing the block.

Returns

• Object: Action object.

selectionChange

Action that changes the position of the user caret.

Parameters

• clientId string|WPSelection: The selected block client ID.
• attributeKey string: The selected block attribute key.
• startOffset number: The start offset.
• endOffset number: The end offset.

Returns

• Object: Action object.

selectNextBlock

Yields action objects used in signalling that the block following the given clientId should be selected.

Parameters

• clientId string: Block client ID.

selectPreviousBlock

Yields action objects used in signalling that the block preceding the given clientId (or optionally, its first parent from bottom to top) should be selected.

Parameters

• clientId string: Block client ID.
• fallbackToParent boolean: If true, select the first parent if there is no previous block.

setBlockEditingMode

Sets the block editing mode for a given block.

Related

• useBlockEditingMode

Parameters

• clientId string: The block client ID, or '' for the root container.
• mode BlockEditingMode: The block editing mode. One of 'disabled', 'contentOnly', or 'default'.

Returns

• Object: Action object.

setBlockMovingClientId

Deprecated

Set the block moving client ID.

Returns

• Object: Action object.

setBlockVisibility

Action that sets whether given blocks are visible on the canvas.

Parameters

• updates Record<string,boolean>: For each block’s clientId, its new visibility setting.

setHasControlledInnerBlocks

Action that sets whether a block has controlled inner blocks.

Parameters

• clientId string: The block’s clientId.
• hasControlledInnerBlocks boolean: True if the block’s inner blocks are controlled.

setTemplateValidity

Action that resets the template validity.

Parameters

• isValid boolean: template validity flag.

Returns

• Object: Action object.

showInsertionPoint

Action that shows the insertion point.

Parameters

• rootClientId ?string: Optional root client ID of block list on which to insert.
• index ?number: Index at which block should be inserted.
• __unstableOptions ?Object: Additional options.

Returns

• Object: Action object.

Properties

• __unstableWithInserter boolean: Whether or not to show an inserter button.
• operation WPDropOperation: The operation to perform when applied, either ‘insert’ or ‘replace’ for now.

startDraggingBlocks

Returns an action object used in signalling that the user has begun to drag blocks.

Parameters

• clientIds string[]: An array of client ids being dragged

Returns

• Object: Action object.

startMultiSelect

Action that starts block multi-selection.

Returns

• Object: Action object.

startTyping

Returns an action object used in signalling that the user has begun to type.

Returns

• Object: Action object.

stopDraggingBlocks

Returns an action object used in signalling that the user has stopped dragging blocks.

Returns

• Object: Action object.

stopMultiSelect

Action that stops block multi-selection.

Returns

• Object: Action object.

stopTyping

Returns an action object used in signalling that the user has stopped typing.

Returns

• Object: Action object.

synchronizeTemplate

Action that synchronizes the template with the list of blocks.

Returns

• Object: Action object.

toggleBlockHighlight

Action that toggles the highlighted block state.

Parameters

• clientId string: The block’s clientId.
• isHighlighted boolean: The highlight state.

toggleBlockMode

Returns an action object used to toggle the block editing mode between visual and HTML modes.

Parameters

• clientId string: Block client ID.

Returns

• Object: Action object.

toggleSelection

Action that enables or disables block selection.

Parameters

• isSelectionEnabled [boolean]: Whether block selection should be enabled.

Returns

• Object: Action object.

unsetBlockEditingMode

Clears the block editing mode for a given block.

Related

• useBlockEditingMode

Parameters

• clientId string: The block client ID, or '' for the root container.

Returns

• Object: Action object.

updateBlock

Action that updates the block with the specified client ID.

Parameters

• clientId string: Block client ID.
• updates Object: Block attributes to be merged.

Returns

• Object: Action object.

updateBlockAttributes

Action that updates attributes of multiple blocks with the specified client IDs.

Parameters

• clientIds string|string[]: Block client IDs.
• attributes Object: Block attributes to be merged. Should be keyed by clientIds if options.uniqueByBlock is true.
• options Object: Updating options.
• options.uniqueByBlock [boolean]: Whether each block in clientIds array has a unique set of attributes.

Returns

• Object: Action object.

updateBlockListSettings

Action that changes the nested settings of the given block(s).

Parameters

• clientId string | SettingsByClientId: Client ID of the block whose nested setting are being received, or object of settings by client ID.
• settings Object: Object with the new settings for the nested block.

Returns

• Object: Action object

updateSettings

Action that updates the block editor settings.

Parameters

• settings Object: Updated settings

Returns

• Object: Action object

validateBlocksToTemplate

Block validity is a function of blocks state (at the point of a reset) and the template setting. As a compromise to its placement across distinct parts of state, it is implemented here as a side effect of the block reset action.

Parameters

• blocks Array: Array of blocks.