Editor

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.

Installation

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.

How it works

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.

Components

Because many blocks share the same complex behaviors, reusable components are made available to simplify implementations of your block's edit function.

`BlockControls`

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 to false.

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.

`RichText`

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 by inline 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 the input and textarea 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 );

API

AlignmentToolbar

Deprecated since 5.3, use wp.blockEditor.AlignmentToolbar instead.

Autocomplete

Deprecated since 5.3, use wp.blockEditor.Autocomplete instead.

AutosaveMonitor

Undocumented declaration.

BlockAlignmentToolbar

Deprecated since 5.3, use wp.blockEditor.BlockAlignmentToolbar instead.

BlockControls

Deprecated since 5.3, use wp.blockEditor.BlockControls instead.

BlockEdit

Deprecated since 5.3, use wp.blockEditor.BlockEdit instead.

BlockEditorKeyboardShortcuts

Deprecated since 5.3, use wp.blockEditor.BlockEditorKeyboardShortcuts instead.

BlockFormatControls

Deprecated since 5.3, use wp.blockEditor.BlockFormatControls instead.

BlockIcon

Deprecated since 5.3, use wp.blockEditor.BlockIcon instead.

BlockInspector

Deprecated since 5.3, use wp.blockEditor.BlockInspector instead.

BlockList

Deprecated since 5.3, use wp.blockEditor.BlockList instead.

BlockMover

Deprecated since 5.3, use wp.blockEditor.BlockMover instead.

BlockNavigationDropdown

Deprecated since 5.3, use wp.blockEditor.BlockNavigationDropdown instead.

BlockSelectionClearer

Deprecated since 5.3, use wp.blockEditor.BlockSelectionClearer instead.

BlockSettingsMenu

Deprecated since 5.3, use wp.blockEditor.BlockSettingsMenu instead.

BlockTitle

Deprecated since 5.3, use wp.blockEditor.BlockTitle instead.

BlockToolbar

Deprecated since 5.3, use wp.blockEditor.BlockToolbar instead.

CharacterCount

Undocumented declaration.

cleanForSlug

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

ColorPalette

Deprecated since 5.3, use wp.blockEditor.ColorPalette instead.

ContrastChecker

Deprecated since 5.3, use wp.blockEditor.ContrastChecker instead.

CopyHandler

Deprecated since 5.3, use wp.blockEditor.CopyHandler instead.

createCustomColorsHOC

Deprecated since 5.3, use wp.blockEditor.createCustomColorsHOC instead.

DefaultBlockAppender

Deprecated since 5.3, use wp.blockEditor.DefaultBlockAppender instead.

DocumentBar

Undocumented declaration.

DocumentOutline

Undocumented declaration.

DocumentOutlineCheck

Undocumented declaration.

EditorHistoryRedo

Undocumented declaration.

EditorHistoryUndo

Undocumented declaration.

EditorKeyboardShortcuts

Undocumented declaration.

EditorKeyboardShortcutsRegister

Undocumented declaration.

EditorNotices

Undocumented declaration.

EditorProvider

Undocumented declaration.

EditorSnackbars

Undocumented declaration.

EntitiesSavedStates

Undocumented declaration.

ErrorBoundary

Undocumented declaration.

FontSizePicker

Deprecated since 5.3, use wp.blockEditor.FontSizePicker instead.

getColorClassName

Deprecated since 5.3, use wp.blockEditor.getColorClassName instead.

getColorObjectByAttributeValues

Deprecated since 5.3, use wp.blockEditor.getColorObjectByAttributeValues instead.

getColorObjectByColorValue

Deprecated since 5.3, use wp.blockEditor.getColorObjectByColorValue instead.

getFontSize

Deprecated since 5.3, use wp.blockEditor.getFontSize instead.

getFontSizeClass

Deprecated since 5.3, use wp.blockEditor.getFontSizeClass instead.

getTemplatePartIcon

Helper function to retrieve the corresponding icon by name.

Parameters

iconName string: The name of the icon.

Returns

Object: The corresponding icon.

InnerBlocks

Deprecated since 5.3, use wp.blockEditor.InnerBlocks instead.

Inserter

Deprecated since 5.3, use wp.blockEditor.Inserter instead.

InspectorAdvancedControls

Deprecated since 5.3, use wp.blockEditor.InspectorAdvancedControls instead.

InspectorControls

Deprecated since 5.3, use wp.blockEditor.InspectorControls instead.

LocalAutosaveMonitor

Undocumented declaration.

MediaPlaceholder

Deprecated since 5.3, use wp.blockEditor.MediaPlaceholder instead.

MediaUpload

Deprecated since 5.3, use wp.blockEditor.MediaUpload instead.

mediaUpload

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.

MediaUploadCheck

Deprecated since 5.3, use wp.blockEditor.MediaUploadCheck instead.

MultiSelectScrollIntoView

Deprecated since 5.3, use wp.blockEditor.MultiSelectScrollIntoView instead.

NavigableToolbar

Deprecated since 5.3, use wp.blockEditor.NavigableToolbar instead.

ObserveTyping

Deprecated since 5.3, use wp.blockEditor.ObserveTyping instead.

PageAttributesCheck

Undocumented declaration.

PageAttributesOrder

Undocumented declaration.

PageAttributesPanel

Undocumented declaration.

PageAttributesParent

Undocumented declaration.

PageTemplate

Undocumented declaration.

PanelColorSettings

Deprecated since 5.3, use wp.blockEditor.PanelColorSettings instead.

PlainText

Deprecated since 5.3, use wp.blockEditor.PlainText instead.

PluginBlockSettingsMenuItem

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.

PluginDocumentSettingPanel

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.

PluginPostPublishPanel

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.

PluginPrePublishPanel

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.

PostAuthor

Undocumented declaration.

PostAuthorCheck

Undocumented declaration.

PostAuthorPanel

Undocumented declaration.

PostComments

Undocumented declaration.

PostDiscussionPanel

Undocumented declaration.

PostExcerpt

Undocumented declaration.

PostExcerptCheck

Undocumented declaration.

PostExcerptPanel

Undocumented declaration.

PostFeaturedImage

Undocumented declaration.

PostFeaturedImageCheck

Undocumented declaration.

PostFeaturedImagePanel

Undocumented declaration.

PostFormat

Undocumented declaration.

PostFormatCheck

Undocumented declaration.

PostLastRevision

Undocumented declaration.

PostLastRevisionCheck

Undocumented declaration.

PostLastRevisionPanel

Undocumented declaration.

PostLockedModal

Undocumented declaration.

PostPendingStatus

Undocumented declaration.

PostPendingStatusCheck

Undocumented declaration.

PostPingbacks

Undocumented declaration.

PostPreviewButton

Undocumented declaration.

PostPublishButton

Undocumented declaration.

PostPublishButtonLabel

Undocumented declaration.

PostPublishPanel

Undocumented declaration.

PostSavedState

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.

PostSchedule

Undocumented declaration.

PostScheduleCheck

Undocumented declaration.

PostScheduleLabel

Undocumented declaration.

PostSchedulePanel

Undocumented declaration.

PostSlug

Undocumented declaration.

PostSlugCheck

Undocumented declaration.

PostSticky

Undocumented declaration.

PostStickyCheck

Undocumented declaration.

PostSwitchToDraftButton

Undocumented declaration.

PostSyncStatus

Undocumented declaration.

PostTaxonomies

Undocumented declaration.

PostTaxonomiesCheck

Undocumented declaration.

PostTaxonomiesFlatTermSelector

Undocumented declaration.

PostTaxonomiesHierarchicalTermSelector

Hierarchical term selector.

Parameters

props Object: Component props.
props.slug string: Taxonomy slug.

Returns

Element: Hierarchical term selector component.

PostTaxonomiesPanel

Undocumented declaration.

PostTemplatePanel

Undocumented declaration.

PostTextEditor

Undocumented declaration.

PostTitle

Undocumented declaration.

PostTitleRaw

Undocumented declaration.

PostTrash

Undocumented declaration.

PostTrashCheck

Undocumented declaration.

PostTypeSupportCheck

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.

PostURL

Undocumented declaration.

PostURLCheck

Undocumented declaration.

PostURLLabel

Undocumented declaration.

PostURLPanel

Undocumented declaration.

PostVisibility

Undocumented declaration.

PostVisibilityCheck

Undocumented declaration.

PostVisibilityLabel

Undocumented declaration.

privateApis

Undocumented declaration.

RichText

Deprecated since 5.3, use wp.blockEditor.RichText instead.

RichTextShortcut

Deprecated since 5.3, use wp.blockEditor.RichTextShortcut instead.

RichTextToolbarButton

Deprecated since 5.3, use wp.blockEditor.RichTextToolbarButton instead.

ServerSideRender

Undocumented declaration.

SkipToSelectedBlock

Deprecated since 5.3, use wp.blockEditor.SkipToSelectedBlock instead.

store

Store definition for the editor namespace.

Related

https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore

Type

Object

storeConfig

Post editor data store configuration.

Related

https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#registerStore

Type

Object

TextEditorGlobalKeyboardShortcuts

Undocumented declaration.

ThemeSupportCheck

Undocumented declaration.

TimeToRead

Undocumented declaration.

transformStyles

Undocumented declaration.

UnsavedChangesWarning

Warns the user if there are unsaved changes before leaving the editor. Compatible with Post Editor and Site Editor.

Returns

Component: The component.

URLInput

Deprecated since 5.3, use wp.blockEditor.URLInput instead.

URLInputButton

Deprecated since 5.3, use wp.blockEditor.URLInputButton instead.

URLPopover

Deprecated since 5.3, use wp.blockEditor.URLPopover instead.

useEntitiesSavedStatesIsDirty

Undocumented declaration.

usePostScheduleLabel

Undocumented declaration.

usePostURLLabel

Undocumented declaration.

usePostVisibilityLabel

Undocumented declaration.

userAutocompleter

A user mentions completer.

Type

WPCompleter

VisualEditorGlobalKeyboardShortcuts

Undocumented declaration.

Warning

Deprecated since 5.3, use wp.blockEditor.Warning instead.

withColorContext

Deprecated since 5.3, use wp.blockEditor.createCustomColorsHOC instead.

withColors

Deprecated since 5.3, use wp.blockEditor.withColors instead.

withFontSizes

Deprecated since 5.3, use wp.blockEditor.withFontSizes instead.

WordCount

Undocumented declaration.

WritingFlow

Deprecated since 5.3, use wp.blockEditor.WritingFlow instead.

Contributing to this package

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.