Skip to main content
Block registration combines a unique name with a configuration object that defines the block’s behavior. While the recommended approach is to use block.json metadata, blocks can also be registered with JavaScript only.

registerBlockType

The registerBlockType function registers a new block type and makes it available to the editor.

Signature

Parameters

  • blockNameOrMetadata - Block name string or metadata object from block.json
  • settings - Block configuration object

Returns

The registered block type, or undefined if registration failed.

Block name

The name must be a unique string structured as namespace/block-name:

Naming requirements

  • Only lowercase alphanumeric characters and dashes
  • Must begin with a letter
  • Must include exactly one forward slash for the namespace
  • Cannot be changed after publication

Namespace best practices

The block name is stored in post content. Changing it requires updating all posts using the block.

Block configuration

title

Type: string (required) The display title shown in the Inserter and throughout the editor. Can be translated.

description

Type: string (optional) Short description shown in the Block Inspector. Can be translated.

category

Type: string (optional) Groups blocks in the Inserter. Core categories:
  • text
  • media
  • design
  • widgets
  • theme
  • embed

icon

Type: string | object (optional) Block icon displayed in the Inserter. Can be:
  • Dashicon slug
  • SVG element
  • Object with background/foreground colors

keywords

Type: string[] (optional) Search terms to help users discover the block. Can be translated.

styles

Type: object[] (optional) Alternative visual styles for the block.

attributes

Type: object (optional) Defines the block’s data structure. See Attributes.

example

Type: object (optional) Provides preview data for the block shown in the Inspector Help Panel.
Set example: {} to show a preview without specific attributes.

variations

Type: object[] (optional) Block variations that share common functionality. Available since WordPress 5.9.

supports

Type: object (optional) Enables block features. See Supports.

transforms

Type: object (optional) Defines how the block can be transformed to/from other blocks.

parent

Type: string[] (optional) Restricts the block to only be available within specified parent blocks.

ancestor

Type: string[] (optional) Makes the block available anywhere within specified ancestor block subtrees. Available since WordPress 6.0.

allowedBlocks

Type: string[] (optional) Specifies which blocks can be direct children. Available since WordPress 6.5.

blockHooks

Type: object (optional) Automatically inserts the block next to specified block types. Available since WordPress 6.4. Positions: before, after, firstChild, lastChild

Registration examples

JavaScript-only registration

Block collections

Group multiple blocks from the same namespace in the Inserter.

registerBlockCollection

Parameters

  • namespace - Matches the block name namespace
  • settings - Object with title and optional icon

Client-side only properties

These properties are only available in JavaScript registration:
  • edit - The Edit component
  • save - The save function
  • transforms - Block transformations
  • deprecated - Deprecated versions
  • merge - Block merging behavior
  • getEditWrapperProps - Additional wrapper props