Skip to main content
The @wordpress/blocks package provides the foundational API for working with blocks in WordPress. It includes functions for registering block types, managing block attributes, parsing and serializing blocks, and handling block transformations.

​
Installation

npm install @wordpress/blocks --save

​
What is a Block?

A block is the abstract term for units of markup that compose the content or layout of a webpage. Blocks combine concepts of shortcodes, custom HTML, and embeds into a single consistent API.

​
Core Functions

​
registerBlockType

Registers a new block type. 
import { registerBlockType } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';

registerBlockType( 'namespace/block-name', {
	title: __( 'My First Block' ),
	edit: () => <div>{ __( 'Hello from the editor!' ) }</div>,
	save: () => <div>Hello from the saved content!</div>,
} );
Parameters:
  • blockNameOrMetadata (string|Object) - Block type name or metadata
  • settings (Object) - Block configuration
Returns: WPBlockType | undefined

​
createBlock

Creates a new block instance. 
import { createBlock } from '@wordpress/blocks';

const block = createBlock( 'core/paragraph', {
	content: 'Hello World',
} );
Parameters:
  • name (string) - Block type name
  • attributes (Object) - Block attributes
  • innerBlocks (Array) - Nested blocks
Returns: Object - Block object

​
parse

Parses post content into blocks. 
import { parse } from '@wordpress/blocks';

const blocks = parse( postContent );
Parameters:
  • content (string) - Post content
  • options (Object) - Parsing options
Returns: Array - Block list

​
serialize

Serializes blocks to post content. 
import { serialize } from '@wordpress/blocks';

const content = serialize( blocks );
Parameters:
  • blocks (Array) - Blocks to serialize
  • options (Object) - Serialization options
Returns: string - Post content

​
Block Registration

​
registerBlockCollection

Groups blocks in the inserter by namespace. 
import { registerBlockCollection } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';

registerBlockCollection( 'my-plugin', {
	title: __( 'My Plugin Blocks' ),
	icon: 'wordpress',
} );

​
registerBlockStyle

Registers alternative block styles. 
import { registerBlockStyle } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';

registerBlockStyle( 'core/quote', {
	name: 'fancy-quote',
	label: __( 'Fancy Quote' ),
} );

​
registerBlockVariation

Registers block variations. 
import { registerBlockVariation } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';

registerBlockVariation( 'core/embed', {
	name: 'youtube',
	title: __( 'YouTube' ),
	attributes: { providerNameSlug: 'youtube' },
} );

​
Block Utilities

​
getBlockType

Retrieves a registered block type. 
import { getBlockType } from '@wordpress/blocks';

const blockType = getBlockType( 'core/paragraph' );

​
getBlockTypes

Returns all registered blocks. 
import { getBlockTypes } from '@wordpress/blocks';

const allBlocks = getBlockTypes();

​
hasBlockSupport

Checks if a block supports a feature. 
import { hasBlockSupport } from '@wordpress/blocks';

const supportsAlign = hasBlockSupport( 'core/image', 'align' );

​
Block Bindings

​
registerBlockBindingsSource

Registers a block bindings source for dynamic attribute values. 
import { registerBlockBindingsSource } from '@wordpress/blocks';
import { _x } from '@wordpress/i18n';

registerBlockBindingsSource( {
	name: 'plugin/custom-source',
	label: _x( 'Custom Source', 'block bindings source' ),
	usesContext: [ 'postId' ],
	getValues: ( { select, context } ) => {
		return {
			content: 'Dynamic content',
		};
	},
} );

​
Block Transforms

​
getBlockTransforms

Retrieves available block transforms. 
import { getBlockTransforms } from '@wordpress/blocks';

const transforms = getBlockTransforms( 'from', 'core/paragraph' );

​
switchToBlockType

Transforms blocks to another type. 
import { switchToBlockType } from '@wordpress/blocks';

const newBlocks = switchToBlockType( block, 'core/heading' );

​
Block Categories

​
setCategories

Defines available block categories. 
import { setCategories } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';

setCategories( [
	{ slug: 'text', title: __( 'Text' ) },
	{ slug: 'media', title: __( 'Media' ) },
	{ slug: 'custom', title: __( 'Custom' ) },
] );

​
Store

The blocks package includes a data store accessible via @wordpress/data: 
import { useSelect } from '@wordpress/data';
import { store as blocksStore } from '@wordpress/blocks';

function MyComponent() {
	const blockTypes = useSelect( ( select ) => {
		return select( blocksStore ).getBlockTypes();
	}, [] );
}

​
Learn More

Build docs developers (and LLMs) love

Get started for freeTalk to us