This module utilizes components from the @wordpress/block-editor
package. Having an awareness of the concept of a WordPress post, it associates the loading and saving mechanism of the value representing blocks to a post and its content. It also provides various components relevant for working with a post object in the context of an editor (e.g., a post title input component). This package can support editing posts of any post type and does not assume that rendering happens in any particular WordPress screen or layout arrangement.
Install the module
npm install @wordpress/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.
The logic flow concerning the editor includes: inferring a block representation of the post content (parsing); describing the state of a post (representation); rendering of the post to the DOM (rendering); attaching controls to manipulate the content a.k.a blocks (UI).
The goal of the editor element is to let the user manipulate the content of their posts in a deterministic way—organized through the presence of blocks of content. Usually, in a declarative flow, the pieces that compose a post would be represented in a certain order and the machine would be able to generate an output view from it with the necessary UI controls. However, we don’t begin in WordPress with a representation of the state of the post that is conductive to this expression nor one that even has any knowledge of blocks because content is stored in a serialized way in a single field.
Such a crucial step is handled by the grammar parsing which takes the serialized content of the post and infers an ordered block list using, preferably, syntax hints present in HTML comments. The editor is initialized with a state representation of the block nodes generated by the parsing of the raw content of a post element: wp.blocks.parse( post.content.raw )
.
The visual editor is thus a component that contains and renders the list of block nodes from the internal state into the page. This removes any trace of imperative handling when it comes to finding a block and manipulating a block. As a matter of fact, the visual editor or the text editor are just two different—equally valid—views of the same representation of state. The internal representation of the post content is updated as blocks are updated and it is serialized back to be saved in post_content
.
Individual blocks are handled by the VisualBlock
component, which attaches event handlers and renders the edit
function of a block definition to the document with the corresponding attributes and local state. The edit
function is the markup shape of a component while in editing mode.
Because many blocks share the same complex behaviors, reusable components are made available to simplify implementations of your block's edit
function.
When returned by your block's edit
implementation, renders a toolbar of icon buttons. This is useful for block-level modifications to be made available when a block is selected. For example, if your block supports alignment, you may want to display alignment options in the selected block's toolbar.
Example:
( function ( editor, React ) {
var el = React.createElement,
BlockControls = editor.BlockControls,
AlignmentToolbar = editor.AlignmentToolbar;
function edit( props ) {
return [
// Controls: (only visible when block is selected)
el(
BlockControls,
{ key: 'controls' },
el( AlignmentToolbar, {
value: props.align,
onChange: function ( nextAlign ) {
props.setAttributes( { align: nextAlign } );
},
} )
),
// Block content: (with alignment as attribute)
el(
'p',
{ key: 'text', style: { textAlign: props.align } },
'Hello World!'
),
];
}
} )( window.wp.editor, window.React );
Note in this example that we render AlignmentToolbar
as a child of the BlockControls
element. This is another pre-configured component you can use to simplify block text alignment.
Alternatively, you can create your own toolbar controls by passing an array of controls
as a prop to the BlockControls
component. Each control should be an object with the following properties:
-
icon: string
- Slug of the Dashicon to be shown in the control's toolbar button -
title: string
- A human-readable localized text to be shown as the tooltip label of the control's button -
subscript: ?string
- Optional text to be shown adjacent the button icon as subscript (for example, heading levels) -
isActive: ?boolean
- Whether the control should be considered active / selected. Defaults tofalse
.
To create divisions between sets of controls within the same BlockControls
element, passing controls
instead as a nested array (array of arrays of objects). A divider will be shown between each set of controls.
Render a rich contenteditable
input, providing users the option to add emphasis to content or links to content. It behaves similarly to a controlled component, except that onChange
is triggered less frequently than would be expected from a traditional input
field, usually when the user exits the field.
The following properties (non-exhaustive list) are made available:
-
value: string
- Markup value of the field. Only valid markup is allowed, as determined byinline
value and available controls. -
onChange: Function
- Callback handler when the value of the field changes, passing the new value as its only argument. -
placeholder: string
- A text hint to be shown to the user when the field value is empty, similar to theinput
andtextarea
attribute of the same name.
Example:
( function ( editor, React ) {
var el = React.createElement,
RichText = editor.RichText;
function edit( props ) {
function onChange( value ) {
props.setAttributes( { text: value } );
}
return el( RichText, {
value: props.attributes.text,
onChange: onChange,
} );
}
// blocks.registerBlockType( ..., { edit: edit, ... } );
} )( window.wp.editor, window.React );
Deprecated since 5.3, use
wp.blockEditor.AlignmentToolbar
instead.
Deprecated since 5.3, use
wp.blockEditor.Autocomplete
instead.
Undocumented declaration.
Deprecated since 5.3, use
wp.blockEditor.BlockAlignmentToolbar
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockControls
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockEdit
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockEditorKeyboardShortcuts
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockFormatControls
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockIcon
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockInspector
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockList
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockMover
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockNavigationDropdown
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockSelectionClearer
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockSettingsMenu
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockTitle
instead.
Deprecated since 5.3, use
wp.blockEditor.BlockToolbar
instead.
Undocumented declaration.
Performs some basic cleanup of a string for use as a post slug
This replicates some of what sanitize_title() does in WordPress core, but is only designed to approximate what the slug will be.
Converts Latin-1 Supplement and Latin Extended-A letters to basic Latin letters. Removes combining diacritical marks. Converts whitespace, periods, and forward slashes to hyphens. Removes any remaining non-word characters except hyphens and underscores. Converts remaining string to lowercase. It does not account for octets, HTML entities, or other encoded characters.
Parameters
-
string
string
: Title or slug to be processed
Returns
-
string
: Processed string
Deprecated since 5.3, use
wp.blockEditor.ColorPalette
instead.
Deprecated since 5.3, use
wp.blockEditor.ContrastChecker
instead.
Deprecated since 5.3, use
wp.blockEditor.CopyHandler
instead.
Deprecated since 5.3, use
wp.blockEditor.createCustomColorsHOC
instead.
Deprecated since 5.3, use
wp.blockEditor.DefaultBlockAppender
instead.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Deprecated since 5.3, use
wp.blockEditor.FontSizePicker
instead.
Deprecated since 5.3, use
wp.blockEditor.getColorClassName
instead.
Deprecated since 5.3, use
wp.blockEditor.getColorObjectByAttributeValues
instead.
Deprecated since 5.3, use
wp.blockEditor.getColorObjectByColorValue
instead.
Deprecated since 5.3, use
wp.blockEditor.getFontSize
instead.
Deprecated since 5.3, use
wp.blockEditor.getFontSizeClass
instead.
Helper function to retrieve the corresponding icon by name.
Parameters
-
iconName
string
: The name of the icon.
Returns
-
Object
: The corresponding icon.
Deprecated since 5.3, use
wp.blockEditor.InnerBlocks
instead.
Deprecated since 5.3, use
wp.blockEditor.Inserter
instead.
Deprecated since 5.3, use
wp.blockEditor.InspectorAdvancedControls
instead.
Deprecated since 5.3, use
wp.blockEditor.InspectorControls
instead.
Undocumented declaration.
Deprecated since 5.3, use
wp.blockEditor.MediaPlaceholder
instead.
Deprecated since 5.3, use
wp.blockEditor.MediaUpload
instead.
Upload a media file when the file upload button is activated. Wrapper around mediaUpload() that injects the current post ID.
Parameters
-
$0
Object
: Parameters object passed to the function. -
$0.additionalData
?Object
: Additional data to include in the request. -
$0.allowedTypes
string
: Array with the types of media that can be uploaded, if unset all types are allowed. -
$0.filesList
Array
: List of files. -
$0.maxUploadFileSize
?number
: Maximum upload size in bytes allowed for the site. -
$0.onError
Function
: Function called when an error happens. -
$0.onFileChange
Function
: Function called each time a file or a temporary representation of the file is available.
Deprecated since 5.3, use
wp.blockEditor.MediaUploadCheck
instead.
Deprecated since 5.3, use
wp.blockEditor.MultiSelectScrollIntoView
instead.
Deprecated since 5.3, use
wp.blockEditor.NavigableToolbar
instead.
Deprecated since 5.3, use
wp.blockEditor.ObserveTyping
instead.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Deprecated since 5.3, use
wp.blockEditor.PanelColorSettings
instead.
Deprecated since 5.3, use
wp.blockEditor.PlainText
instead.
Renders a new item in the block settings menu.
Usage
// Using ES5 syntax
var __ = wp.i18n.__;
var PluginBlockSettingsMenuItem = wp.editor.PluginBlockSettingsMenuItem;
function doOnClick() {
// To be called when the user clicks the menu item.
}
function MyPluginBlockSettingsMenuItem() {
return React.createElement( PluginBlockSettingsMenuItem, {
allowedBlocks: [ 'core/paragraph' ],
icon: 'dashicon-name',
label: __( 'Menu item text' ),
onClick: doOnClick,
} );
}
// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PluginBlockSettingsMenuItem } from '@wordpress/editor';
const doOnClick = () => {
// To be called when the user clicks the menu item.
};
const MyPluginBlockSettingsMenuItem = () => (
<PluginBlockSettingsMenuItem
allowedBlocks={ [ 'core/paragraph' ] }
icon="dashicon-name"
label={ __( 'Menu item text' ) }
onClick={ doOnClick }
/>
);
Parameters
-
props
Object
: Component props. -
props.allowedBlocks
[Array]
: An array containing a list of block names for which the item should be shown. If not present, it'll be rendered for any block. If multiple blocks are selected, it'll be shown if and only if all of them are in the allowed list. -
props.icon
[WPBlockTypeIconRender]
: The Dashicon icon slug string, or an SVG WP element. -
props.label
string
: The menu item text. -
props.onClick
Function
: Callback function to be executed when the user click the menu item. -
props.small
[boolean]
: Whether to render the label or not. -
props.role
[string]
: The ARIA role for the menu item.
Returns
-
Component
: The component to be rendered.
Renders items below the Status & Availability panel in the Document Sidebar.
Usage
// Using ES5 syntax
var el = React.createElement;
var __ = wp.i18n.__;
var registerPlugin = wp.plugins.registerPlugin;
var PluginDocumentSettingPanel = wp.editor.PluginDocumentSettingPanel;
function MyDocumentSettingPlugin() {
return el(
PluginDocumentSettingPanel,
{
className: 'my-document-setting-plugin',
title: 'My Panel',
name: 'my-panel',
},
__( 'My Document Setting Panel' )
);
}
registerPlugin( 'my-document-setting-plugin', {
render: MyDocumentSettingPlugin,
} );
// Using ESNext syntax
import { registerPlugin } from '@wordpress/plugins';
import { PluginDocumentSettingPanel } from '@wordpress/editor';
const MyDocumentSettingTest = () => (
<PluginDocumentSettingPanel
className="my-document-setting-plugin"
title="My Panel"
name="my-panel"
>
<p>My Document Setting Panel</p>
</PluginDocumentSettingPanel>
);
registerPlugin( 'document-setting-test', { render: MyDocumentSettingTest } );
Parameters
-
props
Object
: Component properties. -
props.name
string
: Required. A machine-friendly name for the panel. -
props.className
[string]
: An optional class name added to the row. -
props.title
[string]
: The title of the panel -
props.icon
[WPBlockTypeIconRender]
: The Dashicon icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. -
props.children
Element
: Children to be rendered
Returns
-
Component
: The component to be rendered.
Renders provided content to the post-publish panel in the publish flow (side panel that opens after a user publishes the post).
Usage
// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PluginPostPublishPanel } from '@wordpress/edit-post';
const MyPluginPostPublishPanel = () => (
<PluginPostPublishPanel
className="my-plugin-post-publish-panel"
title={ __( 'My panel title' ) }
initialOpen={ true }
>
{ __( 'My panel content' ) }
</PluginPostPublishPanel>
);
Parameters
-
props
Object
: Component properties. -
props.className
[string]
: An optional class name added to the panel. -
props.title
[string]
: Title displayed at the top of the panel. -
props.initialOpen
[boolean]
: Whether to have the panel initially opened. When no title is provided it is always opened. -
props.icon
[WPBlockTypeIconRender]
: The Dashicon icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. -
props.children
Element
: Children to be rendered
Returns
-
Component
: The component to be rendered.
Renders provided content to the pre-publish side panel in the publish flow (side panel that opens when a user first pushes "Publish" from the main editor).
Usage
// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PluginPrePublishPanel } from '@wordpress/edit-post';
const MyPluginPrePublishPanel = () => (
<PluginPrePublishPanel
className="my-plugin-pre-publish-panel"
title={ __( 'My panel title' ) }
initialOpen={ true }
>
{ __( 'My panel content' ) }
</PluginPrePublishPanel>
);
Parameters
-
props
Object
: Component props. -
props.className
[string]
: An optional class name added to the panel. -
props.title
[string]
: Title displayed at the top of the panel. -
props.initialOpen
[boolean]
: Whether to have the panel initially opened. When no title is provided it is always opened. -
props.icon
[WPBlockTypeIconRender]
: The Dashicon icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. -
props.children
Element
: Children to be rendered
Returns
-
Component
: The component to be rendered.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Component showing whether the post is saved or not and providing save buttons.
Parameters
-
props
Object
: Component props. -
props.forceIsDirty
?boolean
: Whether to force the post to be marked as dirty.
Returns
-
import('react').ComponentType
: The component.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Hierarchical term selector.
Parameters
-
props
Object
: Component props. -
props.slug
string
: Taxonomy slug.
Returns
-
Element
: Hierarchical term selector component.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
A component which renders its own children only if the current editor post type supports one of the given supportKeys
prop.
Parameters
-
props
Object
: Props. -
props.children
Element
: Children to be rendered if post type supports. -
props.supportKeys
(string|string[])
: String or string array of keys to test.
Returns
-
Component
: The component to be rendered.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Deprecated since 5.3, use
wp.blockEditor.RichText
instead.
Deprecated since 5.3, use
wp.blockEditor.RichTextShortcut
instead.
Deprecated since 5.3, use
wp.blockEditor.RichTextToolbarButton
instead.
Undocumented declaration.
Deprecated since 5.3, use
wp.blockEditor.SkipToSelectedBlock
instead.
Store definition for the editor namespace.
Related
Type
Object
Post editor data store configuration.
Related
Type
Object
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Warns the user if there are unsaved changes before leaving the editor. Compatible with Post Editor and Site Editor.
Returns
-
Component
: The component.
Deprecated since 5.3, use
wp.blockEditor.URLInput
instead.
Deprecated since 5.3, use
wp.blockEditor.URLInputButton
instead.
Deprecated since 5.3, use
wp.blockEditor.URLPopover
instead.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
Undocumented declaration.
A user mentions completer.
Type
WPCompleter
Undocumented declaration.
Deprecated since 5.3, use
wp.blockEditor.Warning
instead.
Deprecated since 5.3, use
wp.blockEditor.createCustomColorsHOC
instead.
Deprecated since 5.3, use
wp.blockEditor.withColors
instead.
Deprecated since 5.3, use
wp.blockEditor.withFontSizes
instead.
Undocumented declaration.
Deprecated since 5.3, use
wp.blockEditor.WritingFlow
instead.
This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.
To find out more about contributing to this package or Gutenberg as a whole, please read the project's main contributor guide.