data-core-block-editor.md

The Block Editor’s Data

Namespace: core/block-editor.

Selectors

# 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.

# 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.

# 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.

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.

# 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.
• rootClientId ?string: Optional root client ID of block list.

Returns

• number: Index at which block exists in order.

# getBlockInsertionPoint

Returns the insertion point, the index at which the new inserted block would be placed. 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.

# 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.

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: It's important to memoize this selector to avoid return a new instance on each call

Parameters

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

Returns

• Array<Object>: Post blocks.

# getBlocksByClientId

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

Parameters

• state Object: Editor state.
• clientIds Array<string>: Client IDs for which blocks are to be returned.

Returns

• Array<WPBlock>: Block objects.

# 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.

# getClientIdsOfDescendants

Returns an array containing the clientIds of all descendants of the blocks given.

Parameters

• state Object: Global application state.
• clientIds Array: Array of blocks to inspect.

Returns

• Array: ids of descendants.

# getClientIdsWithDescendants

Returns an array containing the clientIds of the top-level blocks and their descendants of any depth (for nested blocks).

Parameters

• state Object: Global application state.

Returns

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

# 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.

# 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 'utility' property indicates how useful we think an item will be to the user. There are 4 levels of utility:

1. Blocks that are contextually useful (utility = 3)
2. Blocks that have been previously inserted (utility = 2)
3. Blocks that are in the common category (utility = 1)
4. All other blocks (utility = 0)

The 'frecency' property is a heuristic (https://en.wikipedia.org/wiki/Frecency) that combines block usage frequenty 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

• Array<WPEditorInserterItem>: Items that appear in inserter.

# 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.

# 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.

# 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.

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.

Parameters

• state Object: Global application state.

Returns

• ?Object: Selected block.

# 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: Block Template Lock

# 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 as an inner block selected

# 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.

# isBlockInsertionPointVisible

Returns true if we should show the block insertion point.

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.

# 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

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

Parameters

• state Object: Global application state.

Returns

• boolean: Whether the caret is within formatted text.

# 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.

# 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.

# isNavigationMode

Returns whether the navigation mode is enabled.

Parameters

• state Object: Editor state.

Returns

• boolean: Is navigation mode enabled.

# 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.

# isValidTemplate

Returns whether the blocks matches the template or not.

Parameters

• state boolean:

Returns

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

Actions

# clearSelectedBlock

Returns an action object used in signalling that the block selection is cleared.

Returns

• Object: Action object.

# enterFormattedText

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

Returns

• Object: Action object.

# exitFormattedText

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

Returns

• Object: Action object.

# hideInsertionPoint

Returns an action object hiding the insertion point.

Returns

• Object: Action object.

# insertBlock

Returns an action object used in signalling that a single block should be inserted, optionally at a specific index respective a root 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.

Returns

• Object: Action object.

# insertBlocks

Returns an action object used in signalling that an array of blocks should be inserted, optionally at a specific index respective a root block list.

Parameters

• blocks Array<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.

Returns

• Object: Action object.

# insertDefaultBlock

Returns an action object used in signalling that a new block of the default type should be added 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

Returns

• Object: Action object

# mergeBlocks

Returns an action object used in signalling that two blocks should be merged

Parameters

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

Returns

• Object: Action object.

# moveBlocksDown

Undocumented declaration.

# moveBlocksUp

Undocumented declaration.

# moveBlockToPosition

Returns an action object signalling that an indexed block should be moved to a new index.

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 into.

# multiSelect

Returns an action object used in signalling that block multi-selection changed.

Parameters

• start string: First block of the multi selection.
• end string: Last block of the multiselection.

Returns

• Object: Action object.

# receiveBlocks

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 Array<Object>: Array of block objects.

Returns

• Object: Action object.

# 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|Array<string>): Client IDs of blocks to remove.
• selectPrevious boolean: True if the previous block should be selected when a block is removed.

# replaceBlock

Returns an action object signalling that a single block should be replaced with one or more replacement blocks.

Parameters

• clientId (string|Array<string>): Block client ID to replace.
• block (Object|Array<Object>): Replacement block(s).

Returns

• Object: Action object.

# replaceBlocks

Returns an action object signalling that a blocks should be replaced with one or more replacement blocks.

Parameters

• clientIds (string|Array<string>): Block client ID(s) to replace.
• blocks (Object|Array<Object>): Replacement block(s).
• indexToSelect number: Index of replacement block to select.

# 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 Array<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 true.

Returns

• Object: Action object.

# resetBlocks

Returns an action object used in signalling that blocks state should be reset to the specified array of blocks, taking precedence over any other content reflected as an edit in state.

Parameters

• blocks Array: Array of blocks.

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 ?number: Optional initial position. Pass as -1 to reflect reverse selection.

Returns

• Object: Action object.

# selectionChange

Returns an action object used in signalling that the user caret has changed position.

Parameters

• clientId string: 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 should be selected.

Parameters

• clientId string: Block client ID.

# setNavigationMode

Returns an action object used to enable or disable the navigation mode.

Parameters

• isNavigationMode string: Enable/Disable navigation mode.

Returns

• Object: Action object

# setTemplateValidity

Returns an action object resetting the template validity.

Parameters

• isValid boolean: template validity flag.

Returns

• Object: Action object.

# showInsertionPoint

Returns an action object used in signalling that the insertion point should be shown.

Parameters

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

Returns

• Object: Action object.

# startMultiSelect

Returns an action object used in signalling that a block multi-selection has started.

Returns

• Object: Action object.

# startTyping

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

Returns

• Object: Action object.

# stopMultiSelect

Returns an action object used in signalling that block multi-selection stopped.

Returns

• Object: Action object.

# stopTyping

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

Returns

• Object: Action object.

# synchronizeTemplate

Returns an action object synchronize the template with the list of blocks

Returns

• Object: Action object.

# 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

Returns an action object that enables or disables block selection.

Parameters

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

Returns

• Object: Action object.

# updateBlock

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

Parameters

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

Returns

• Object: Action object.

# updateBlockAttributes

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

Parameters

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

Returns

• Object: Action object.

# updateBlockListSettings

Returns an action object that changes the nested settings of a given block.

Parameters

• clientId string: Client ID of the block whose nested setting are being received.
• settings Object: Object with the new settings for the nested block.

Returns

• Object: Action object

# updateSettings

Undocumented declaration.