@wordpress/block-editor

The @wordpress/block-editor package provides generic, WordPress-agnostic components and hooks for creating block editors. This is the foundational layer of the Gutenberg editor architecture.

Installation

npm install @wordpress/block-editor --save

Current Version: 15.13.1This package assumes an ES2015+ environment. Include the polyfill from @wordpress/babel-preset-default if needed.

Architecture

The @wordpress/block-editor is the first layer in Gutenberg’s three-layer architecture:

Block Editor (Generic Layer)

@wordpress/block-editor - WordPress-agnostic block editing

Editor (WordPress Layer)

@wordpress/editor - WordPress post-type aware

Implementation Layer

@wordpress/edit-post, @wordpress/edit-site - Full editor screens

This package is WordPress-agnostic. NEVER add @wordpress/core-data dependencies or direct REST API calls. Keep it generic and reusable.

Quick Start

Create a standalone block editor:

import { useState } from 'react';
import {
  BlockCanvas,
  BlockEditorProvider,
  BlockList,
} from '@wordpress/block-editor';
import { registerCoreBlocks } from '@wordpress/block-library';

// Register core blocks
registerCoreBlocks();

function MyEditor() {
  const [ blocks, updateBlocks ] = useState( [] );

  return (
    <BlockEditorProvider
      value={ blocks }
      onInput={ updateBlocks }
      onChange={ updateBlocks }
    >
      <BlockCanvas height="400px" />
    </BlockEditorProvider>
  );
}

Don’t forget to load the required stylesheets:

import '@wordpress/components/build-style/style.css';
import '@wordpress/block-editor/build-style/style.css';
import '@wordpress/block-library/build-style/style.css';

Core Components

BlockEditorProvider

The root component that provides block editor context.

import { BlockEditorProvider } from '@wordpress/block-editor';

<BlockEditorProvider
  value={ blocks }
  onInput={ onInput }
  onChange={ onChange }
  settings={ settings }
>
  { /* Your editor UI */ }
</BlockEditorProvider>

Array

required

Current array of blocks

Function

Called when blocks change (non-persistent changes like typing)

Function

Called when blocks change (persistent changes like adding blocks)

Object

Editor settings object. See SETTINGS_DEFAULTS

BlockCanvas

Renders the block list in an iframe for content isolation.

import { BlockCanvas } from '@wordpress/block-editor';

<BlockCanvas 
  height="400px"
  styles={ contentStyles }
>
  { /* Optional: Custom children (defaults to BlockList) */ }
</BlockCanvas>

string

Canvas height (defaults to 300px)

Array

Content styles to inject into the iframe

Element

Content to render (defaults to BlockList component)

BlockList

Renders the list of blocks.

import { BlockList } from '@wordpress/block-editor';

<BlockList />

This component automatically renders all blocks from the BlockEditorProvider context.

BlockInspector

Displays block settings in a sidebar.

import { BlockInspector } from '@wordpress/block-editor';

<div className="sidebar">
  <BlockInspector />
</div>

Shows settings for the currently selected block.

BlockTools

Renders toolbars and insertion points for blocks.

import { BlockTools } from '@wordpress/block-editor';

<BlockTools
  __unstableContentRef={ contentRef }
>
  { children }
</BlockTools>

Object

required

The block content and style container

Object

Ref holding the content scroll container

BlockToolbar

Renders the block toolbar with controls.

import { BlockToolbar } from '@wordpress/block-editor';

<BlockToolbar 
  hideDragHandle={ false }
  variant="toolbar-block"
/>

boolean

Show or hide the drag handle

string

Style variant (‘toolbar-block’ or ‘toolbar’)

Block Controls

BlockControls

Renders controls in the block toolbar.

import { BlockControls } from '@wordpress/block-editor';
import { ToolbarButton } from '@wordpress/components';
import { formatBold } from '@wordpress/icons';

function Edit( { attributes, setAttributes } ) {
  return (
    <>
      <BlockControls>
        <ToolbarButton
          icon={ formatBold }
          label="Bold"
          onClick={ toggleBold }
        />
      </BlockControls>
      { /* Block content */ }
    </>
  );
}

InspectorControls

Renders controls in the block inspector sidebar.

import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody, TextControl } from '@wordpress/components';

function Edit( { attributes, setAttributes } ) {
  return (
    <>
      <InspectorControls>
        <PanelBody title="Settings">
          <TextControl
            label="Custom Text"
            value={ attributes.text }
            onChange={ ( text ) => setAttributes( { text } ) }
          />
        </PanelBody>
      </InspectorControls>
      { /* Block content */ }
    </>
  );
}

InspectorAdvancedControls

Renders advanced controls in the block inspector.

import { InspectorAdvancedControls } from '@wordpress/block-editor';
import { TextControl } from '@wordpress/components';

<InspectorAdvancedControls>
  <TextControl
    label="HTML Anchor"
    value={ attributes.anchor }
    onChange={ ( anchor ) => setAttributes( { anchor } ) }
  />
</InspectorAdvancedControls>

Alignment Controls

AlignmentControl

Text alignment control.

import { AlignmentControl } from '@wordpress/block-editor';

<AlignmentControl
  value={ attributes.align }
  onChange={ ( align ) => setAttributes( { align } ) }
/>

BlockAlignmentControl

Block-level alignment control.

import { BlockAlignmentControl } from '@wordpress/block-editor';

<BlockAlignmentControl
  value={ attributes.align }
  onChange={ ( align ) => setAttributes( { align } ) }
  controls={ [ 'left', 'center', 'right', 'wide', 'full' ] }
/>

BlockVerticalAlignmentControl

Vertical alignment control for blocks.

import { BlockVerticalAlignmentControl } from '@wordpress/block-editor';

<BlockVerticalAlignmentControl
  value={ attributes.verticalAlignment }
  onChange={ ( verticalAlignment ) => 
    setAttributes( { verticalAlignment } )
  }
/>

Rich Text

RichText

Multi-line rich text input for content editing.

import { RichText, useBlockProps } from '@wordpress/block-editor';

function Edit( { attributes, setAttributes } ) {
  const blockProps = useBlockProps();
  
  return (
    <RichText
      { ...blockProps }
      tagName="p"
      value={ attributes.content }
      onChange={ ( content ) => setAttributes( { content } ) }
      placeholder="Enter text..."
    />
  );
}

function Save( { attributes } ) {
  const blockProps = useBlockProps.save();
  
  return (
    <RichText.Content
      { ...blockProps }
      tagName="p"
      value={ attributes.content }
    />
  );
}

string

required

HTML tag to use (e.g., ‘p’, ‘h2’, ‘div’)

string

required

Rich text HTML value

Function

required

Called when content changes

string

Placeholder text when empty

PlainText

Plain text input without formatting.

import { PlainText } from '@wordpress/block-editor';

<PlainText
  value={ attributes.code }
  onChange={ ( code ) => setAttributes( { code } ) }
  placeholder="Enter code..."
/>

Colors and Styles

ColorPalette

Color picker with palette.

import { ColorPalette } from '@wordpress/block-editor';

<ColorPalette
  value={ attributes.backgroundColor }
  onChange={ ( backgroundColor ) => setAttributes( { backgroundColor } ) }
/>

PanelColorSettings

Color settings panel for the inspector.

import { PanelColorSettings } from '@wordpress/block-editor';

<PanelColorSettings
  title="Color Settings"
  colorSettings={ [
    {
      value: attributes.backgroundColor,
      onChange: ( backgroundColor ) => setAttributes( { backgroundColor } ),
      label: 'Background Color',
    },
    {
      value: attributes.textColor,
      onChange: ( textColor ) => setAttributes( { textColor } ),
      label: 'Text Color',
    },
  ] }
/>

withColors

Higher-order component for color management.

import { withColors } from '@wordpress/block-editor';
import { compose } from '@wordpress/compose';

function Edit( { backgroundColor, setBackgroundColor, textColor, setTextColor } ) {
  return (
    <div style={{ backgroundColor: backgroundColor.color, color: textColor.color }}>
      Content
    </div>
  );
}

export default compose(
  withColors( 'backgroundColor', { textColor: 'color' } )
)( Edit );

Typography

FontSizePicker

Font size picker control.

import { FontSizePicker } from '@wordpress/block-editor';

<FontSizePicker
  value={ attributes.fontSize }
  onChange={ ( fontSize ) => setAttributes( { fontSize } ) }
/>

LineHeightControl

Line height control.

import { LineHeightControl } from '@wordpress/block-editor';

<LineHeightControl
  value={ attributes.lineHeight }
  onChange={ ( lineHeight ) => setAttributes( { lineHeight } ) }
/>

Media

MediaPlaceholder

Placeholder for media upload.

import { MediaPlaceholder } from '@wordpress/block-editor';

<MediaPlaceholder
  icon="format-image"
  labels={ {
    title: 'Image',
    instructions: 'Upload an image or pick one from your media library.',
  } }
  onSelect={ ( media ) => setAttributes( { mediaId: media.id, mediaUrl: media.url } ) }
  accept="image/*"
  allowedTypes={ [ 'image' ] }
/>

MediaUpload

Media upload button.

import { MediaUpload } from '@wordpress/block-editor';
import { Button } from '@wordpress/components';

<MediaUpload
  onSelect={ ( media ) => setAttributes( { imageUrl: media.url } ) }
  allowedTypes={ [ 'image' ] }
  value={ attributes.imageId }
  render={ ( { open } ) => (
    <Button onClick={ open }>
      { attributes.imageUrl ? 'Replace Image' : 'Select Image' }
    </Button>
  ) }
/>

MediaReplaceFlow

Media replacement control.

import { MediaReplaceFlow } from '@wordpress/block-editor';

<MediaReplaceFlow
  mediaId={ attributes.mediaId }
  mediaURL={ attributes.mediaUrl }
  allowedTypes={ [ 'image' ] }
  accept="image/*"
  onSelect={ ( media ) => setAttributes( { mediaId: media.id, mediaUrl: media.url } ) }
/>

Inner Blocks

InnerBlocks

Nested blocks support.

import { InnerBlocks, useBlockProps } from '@wordpress/block-editor';

function Edit() {
  const blockProps = useBlockProps();
  
  return (
    <div { ...blockProps }>
      <InnerBlocks
        allowedBlocks={ [ 'core/paragraph', 'core/heading' ] }
        template={ [
          [ 'core/heading', { placeholder: 'Title...' } ],
          [ 'core/paragraph', { placeholder: 'Content...' } ],
        ] }
      />
    </div>
  );
}

function Save() {
  const blockProps = useBlockProps.save();
  
  return (
    <div { ...blockProps }>
      <InnerBlocks.Content />
    </div>
  );
}

Array

Array of block names that can be inserted

Array

Initial block template as array of [blockName, attributes, innerBlocks]

string | false

all: Prevents all operations
insert: Prevents inserting/removing blocks
false: No restrictions

Hooks

useBlockProps

Essential hook for marking block elements.

import { useBlockProps } from '@wordpress/block-editor';

function Edit() {
  const blockProps = useBlockProps( {
    className: 'my-custom-class',
    style: {
      backgroundColor: '#eeeeee',
    },
  } );
  
  return <div { ...blockProps }>Content</div>;
}

Required for all blocks using API version 2 or higher.

useInnerBlocksProps

Combines useBlockProps with inner blocks.

import { useBlockProps, useInnerBlocksProps } from '@wordpress/block-editor';

function Edit() {
  const blockProps = useBlockProps();
  const innerBlocksProps = useInnerBlocksProps( blockProps, {
    allowedBlocks: [ 'core/paragraph' ],
  } );
  
  return <div { ...innerBlocksProps } />;
}

useBlockEditContext

Access current block context.

import { useBlockEditContext } from '@wordpress/block-editor';

function MyComponent() {
  const { name, clientId, isSelected } = useBlockEditContext();
  
  return (
    <div>
      Block { name } ({ clientId }) is { isSelected ? 'selected' : 'not selected' }
    </div>
  );
}

string

Block type name

string

Unique block client ID

boolean

Whether the block is selected

useSettings

Retrieve editor settings.

import { useSettings } from '@wordpress/block-editor';

function MyComponent() {
  const [ enableCustomSpacing, colors ] = useSettings(
    'spacing.customPadding',
    'color.palette'
  );
  
  return <div>Custom spacing: { enableCustomSpacing ? 'yes' : 'no' }</div>;
}

useBlockDisplayInformation

Get block display information.

import { useBlockDisplayInformation } from '@wordpress/block-editor';

function BlockTitle( { clientId } ) {
  const { title, icon } = useBlockDisplayInformation( clientId );
  
  return <div>{ icon } { title }</div>;
}

useBlockEditingMode

Control block editing mode.

import { useBlockEditingMode } from '@wordpress/block-editor';

function MyBlock() {
  // Disable editing for this block
  useBlockEditingMode( 'disabled' );
  
  return <div>This block cannot be edited</div>;
}

BlockEditingMode

'disabled': Block cannot be selected
'contentOnly': Hide non-content UI
'default': Normal editing

Utility Functions

getColorClassName

Returns a color class name.

import { getColorClassName } from '@wordpress/block-editor';

const className = getColorClassName( 'background-color', 'vivid-red' );
// "has-vivid-red-background-color"

getFontSizeClass

Returns a font size class name.

import { getFontSizeClass } from '@wordpress/block-editor';

const className = getFontSizeClass( 'large' );
// "has-large-font-size"

getTypographyClassesAndStyles

Get typography CSS classes and styles from attributes.

import { getTypographyClassesAndStyles } from '@wordpress/block-editor';

const { classNames, style } = getTypographyClassesAndStyles( attributes );

SETTINGS_DEFAULTS

Default editor settings object:

import { SETTINGS_DEFAULTS } from '@wordpress/block-editor';

const mySettings = {
  ...SETTINGS_DEFAULTS,
  alignWide: true,
  colors: [
    { name: 'Red', slug: 'red', color: '#ff0000' },
    { name: 'Blue', slug: 'blue', color: '#0000ff' },
  ],
};

Available Settings

boolean

Enable/disable wide/full alignments

boolean

Enable/disable layout support

Array

Available color palette

Array

Available font sizes

Array

Available image sizes

number

Max content width

boolean | Array

Allowed block types (true for all, array for specific)

Whether toolbar is fixed at top

boolean

Enable focus mode

Array

Editor styles

string

Placeholder for empty content

Store

The block-editor package includes a data store:

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

function MyComponent() {
  const selectedBlock = useSelect( ( select ) => {
    return select( blockEditorStore ).getSelectedBlock();
  }, [] );
  
  const { insertBlock } = useDispatch( blockEditorStore );
  
  return <div>Selected: { selectedBlock?.name }</div>;
}

TypeScript

Type definitions are included:

import type { BlockEditProps } from '@wordpress/block-editor';

interface Attributes {
  content: string;
  alignment: string;
}

function Edit( props: BlockEditProps< Attributes > ) {
  const { attributes, setAttributes } = props;
  return <div>{ attributes.content }</div>;
}

Dependencies

Key dependencies:

@wordpress/blocks - Block API
@wordpress/components - UI components
@wordpress/data - State management
@wordpress/element - React abstraction
@wordpress/i18n - Internationalization
@wordpress/compose - Higher-order components
And 20+ other packages

See package.json for the complete list.

Resources

Block Editor Handbook

Complete block editor documentation

Custom Block Editor

How to create a custom block editor

GitHub Repository

Source code and issue tracker

Component READMEs

Detailed component documentation

​@wordpress/block-editor

​Installation

​Architecture

​Quick Start

​Core Components

​BlockEditorProvider

​BlockCanvas

​BlockList

​BlockInspector

​BlockTools

​BlockToolbar

​Block Controls

​BlockControls

​InspectorControls

​InspectorAdvancedControls

​Alignment Controls

​AlignmentControl

​BlockAlignmentControl

​BlockVerticalAlignmentControl

​Rich Text

​RichText

​PlainText

​Colors and Styles

​ColorPalette

​PanelColorSettings

​withColors

​Typography

​FontSizePicker

​LineHeightControl

​Media

​MediaPlaceholder

​MediaUpload

​MediaReplaceFlow

​Inner Blocks

​InnerBlocks

​Hooks

​useBlockProps

​useInnerBlocksProps

​useBlockEditContext

​useSettings

​useBlockDisplayInformation

​useBlockEditingMode

​Utility Functions

​getColorClassName

​getFontSizeClass

​getTypographyClassesAndStyles

​SETTINGS_DEFAULTS

​Store

​TypeScript

​Dependencies

​Resources

Block Editor Handbook

Custom Block Editor

GitHub Repository

Component READMEs

@wordpress/block-editor

Installation

Architecture

Quick Start

Core Components

BlockEditorProvider

BlockCanvas

BlockList

BlockInspector

BlockTools

BlockToolbar

Block Controls

BlockControls

InspectorControls

InspectorAdvancedControls

Alignment Controls

AlignmentControl

BlockAlignmentControl

BlockVerticalAlignmentControl

Rich Text

RichText

PlainText

Colors and Styles

ColorPalette

PanelColorSettings

withColors

Typography

FontSizePicker

LineHeightControl

Media

MediaPlaceholder

MediaUpload

MediaReplaceFlow

Inner Blocks

InnerBlocks

Hooks

useBlockProps

useInnerBlocksProps

useBlockEditContext

useSettings

useBlockDisplayInformation

useBlockEditingMode

Utility Functions

getColorClassName

getFontSizeClass

getTypographyClassesAndStyles

SETTINGS_DEFAULTS

Store

TypeScript

Dependencies

Resources