“Block” is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage. The idea combines concepts of what in WordPress today we achieve with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.
For more context, refer to What Are Little Blocks Made Of? from the Make WordPress Design blog.
Installation
Install the module
npm install @wordpress/blocks --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
cloneBlock
Given a block object, returns a copy of the block object, optionally merging new attributes and/or replacing its inner blocks.
Parameters
- block
Object: Block instance. - mergeAttributes
Object: Block attributes. - newInnerBlocks
?Array: Nested blocks.
Returns
Object: A cloned block.
createBlock
Returns a block object given its type and attributes.
Parameters
- name
string: Block name. - attributes
Object: Block attributes. - innerBlocks
?Array: Nested blocks.
Returns
Object: Block object.
createBlocksFromInnerBlocksTemplate
Given an array of InnerBlocks templates or Block Objects, returns an array of created Blocks from them. It handles the case of having InnerBlocks as Blocks by converting them to the proper format to continue recursively.
Parameters
- innerBlocksOrTemplate
Array: Nested blocks or InnerBlocks templates.
Returns
Object[]: Array of Block objects.
doBlocksMatchTemplate
Checks whether a list of blocks matches a template by comparing the block names.
Parameters
- blocks
Array: Block list. - template
Array: Block template.
Returns
boolean: Whether the list of blocks matches a templates.
findTransform
Given an array of transforms, returns the highest-priority transform where the predicate function returns a truthy value. A higher-priority transform is one with a lower priority value (i.e. first in priority order). Returns null if the transforms set is empty or the predicate function returns a falsey value for all entries.
Parameters
- transforms
Object[]: Transforms to search. - predicate
Function: Function returning true on matching transform.
Returns
?Object: Highest-priority transform candidate.
getBlockAttributes
Returns the block attributes of a registered block node given its type.
Parameters
- blockTypeOrName
string|Object: Block type or name. - innerHTML
string|Node: Raw block content. - attributes
?Object: Known block attributes (from delimiters).
Returns
Object: All block attributes.
getBlockAttributesNamesByRole
Filter block attributes by role and return their names.
Parameters
- name
string: Block attribute’s name. - role
string: The role of a block attribute.
Returns
string[]: The attribute names that have the provided role.
getBlockBindingsSource
Returns a registered block bindings source by its name.
Parameters
- name
string: Block bindings source name.
Returns
?Object: Block bindings source.
Changelog
6.7.0 Introduced in WordPress core.
getBlockBindingsSources
Returns all registered block bindings sources.
Returns
Array: Block bindings sources.
Changelog
6.7.0 Introduced in WordPress core.
getBlockContent
Given a block object, returns the Block’s Inner HTML markup.
Parameters
- block
Object: Block instance.
Returns
string: HTML.
getBlockDefaultClassName
Returns the block’s default classname from its name.
Parameters
- blockName
string: The block name.
Returns
string: The block’s default class.
getBlockFromExample
Create a block object from the example API.