@wordpress/block-editor

This module allows you to create and use standalone block editors.

Installation

Install the module

npm install @wordpress/block-editor --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.

Usage

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

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

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

// Make sure to load the block editor stylesheets too
// import '@wordpress/components/build-style/style.css';
// import '@wordpress/block-editor/build-style/style.css';

In this example, we’re instantiating a block editor. A block editor is composed by a BlockEditorProvider wrapper component where you pass the current array of blocks and on each change the onInput or onChange callbacks are called depending on whether the change is considered persistent or not.

Inside BlockEditorProvider, you can nest any of the available @wordpress/block-editor UI components to build the UI of your editor.

In the example above we’re rendering the BlockList to show and edit the block list. For instance we could add a custom sidebar and use the BlockInspector component to be able to edit the advanced settings for the currently selected block. (See the API for the list of all the available components).

The BlockTools component is used to render the toolbar for a selected block.

In the example above, there’s no registered block type, in order to use the block editor successfully make sure to register some block types. For instance, registering the core block types can be done like so:

import { registerCoreBlocks } from '@wordpress/block-library';

registerCoreBlocks();

// Make sure to load the block stylesheets too
// import '@wordpress/block-library/build-style/style.css';
// import '@wordpress/block-library/build-style/editor.css';
// import '@wordpress/block-library/build-style/theme.css';

API

Any components in this package that have a counterpart in @wordpress/components are an extension of those components.

Unless you’re creating an editor, it is recommended that the components in @wordpress/components should be used rather than the ones in this package as these components have been customized for use in an editor and may result in unexpected behaviour if used outside of this context.