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 buttontitle: string
– A human-readable localized text to be shown as the tooltip label of the control’s buttonsubscript: ?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.
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 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 the
input
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 );
API
AlignmentToolbar
Deprecated since 5.3, use
wp.blockEditor.AlignmentToolbar
instead.
Autocomplete
Deprecated since 5.3, use
wp.blockEditor.Autocomplete
instead.
AutosaveMonitor
Monitors the changes made to the edited post and triggers autosave if necessary.
The logic is straightforward: a check is performed every props.interval
seconds. If any changes are detected, props.autosave()
is called. The time between the change and the autosave varies but is no larger than props.interval
seconds. Refer to the code below for more details, such as the specific way of detecting changes.
There are two caveats:
- If
props.isAutosaveable
happens to be false at a time of checking for changes, the check is retried every second. - The timer may be disabled by setting
props.disableIntervalChecks
totrue
. In that mode, any change will immediately triggerprops.autosave()
.
Usage
<AutosaveMonitor interval={ 30000 } />
Parameters
- props
Object
: – The properties passed to the component. - props.autosave
Function
: – The function to call when changes need to be saved. - props.interval
number
: – The maximum time in seconds between an unsaved change and an autosave. - props.isAutosaveable
boolean
: – If false, the check for changes is retried every second. - props.disableIntervalChecks
boolean
: – If true, disables the timer and any change will immediately triggerprops.autosave()
. - props.isDirty
boolean
: – Indicates if there are unsaved changes.
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
Renders the character count of the post content.
Returns
number
: The character count.
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
This component renders a navigation bar at the top of the editor. It displays the title of the current document, a back button (if applicable), and a command center button. It also handles different states of the document, such as “not found” or “unsynced”.
Usage
<DocumentBar />
Parameters
- props
Object
: The component props. - props.title
string
: A title for the document, defaulting to the document or template title currently being edited. - props.icon
IconType
: An icon for the document, no default. (A default icon indicating the document post type is no longer used.)
Returns
JSX.Element
: The rendered DocumentBar component.
DocumentOutline
Renders a document outline component.
Parameters
- props
Object
: Props. - props.onSelect
Function
: Function to be called when an outline item is selected. - props.isTitleSupported
boolean
: Indicates whether the title is supported. - props.hasOutlineItemsDisabled
boolean
: Indicates whether the outline items are disabled.
Returns
Component
: The component to be rendered.
DocumentOutlineCheck
Component check if there are any headings (core/heading blocks) present in the document.
Parameters
- props
Object
: Props. - props.children
Element
: Children to be rendered.
Returns
Component|null
: The component to be rendered or null if there are headings.
EditorHistoryRedo
Renders the redo button for the editor history.
Parameters
- props
Object
: – Props. - ref
Ref
: – Forwarded ref.
Returns
Component
: The component to be rendered.
EditorHistoryUndo
Renders the undo button for the editor history.
Parameters
- props
Object
: – Props. - ref
Ref
: – Forwarded ref.
Returns
Component
: The component to be rendered.
EditorKeyboardShortcuts
Handles the keyboard shortcuts for the editor.
It provides functionality for various keyboard shortcuts such as toggling editor mode, toggling distraction-free mode, undo/redo, saving the post, toggling list view, and toggling the sidebar.
EditorKeyboardShortcutsRegister
Component for registering editor keyboard shortcuts.
Returns
Element
: The component to be rendered.
EditorNotices
This component renders the notices displayed in the editor. It displays pinned notices first, followed by dismissible
Usage
<EditorNotices />
Returns
JSX.Element
: The rendered EditorNotices component.
EditorProvider
This component establishes a new post editing context, and serves as the entry point for a new post editor (or post with template editor).
It supports a large number of post types, including post, page, templates, custom post types, patterns, template parts.
All modification and changes are performed to the @wordpress/core-data
store.
Usage
<EditorProvider
post={ post }
settings={ settings }
__unstableTemplate={ template }
>
{ children }
</EditorProvider>
Parameters
- props
Object
: The component props. - props.post
[Object]
: The post object to edit. This is required. - props.__unstableTemplate
[Object]
: The template object wrapper the edited post. This is optional and can only be used when the post type supports templates (like posts and pages). - props.settings
[Object]
: The settings object to use for the editor. This is optional and can be used to override the default settings. - props.children
[Element]
: Children elements for which the BlockEditorProvider context should apply. This is optional.
Returns
JSX.Element
: The rendered EditorProvider component.
EditorSnackbars
Renders the editor snackbars component.
Returns
JSX.Element
: The rendered component.
EntitiesSavedStates
Renders the component for managing saved states of entities.
Parameters
- props
Object
: The component props. - props.close
Function
: The function to close the dialog. - props.renderDialog
Function
: The function to render the dialog.
Returns
JSX.Element
: The rendered component.
ErrorBoundary
ErrorBoundary is used to catch JavaScript errors anywhere in a child component tree, log those errors, and display a fallback UI.
It uses the lifecycle methods getDerivedStateFromError and componentDidCatch to catch errors in a child component tree.
getDerivedStateFromError is used to render a fallback UI after an error has been thrown, and componentDidCatch is used to log error information.
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
Monitors local autosaves of a post in the editor. It uses several hooks and functions to manage autosave behavior:
useAutosaveNotice
hook: Manages the creation of a notice prompting the user to restore a local autosave, if one exists.useAutosavePurge
hook: Ejects a local autosave after a successful save occurs.hasSessionStorageSupport
function: Checks if the current environment supports browser sessionStorage.LocalAutosaveMonitor
component: Uses theAutosaveMonitor
component to perform autosaves at a specified interval.
The module also checks for sessionStorage support and conditionally exports the LocalAutosaveMonitor
component based on that.
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
Wrapper component that renders its children only if the post type supports page attributes.
Parameters
- props
Object
: – The component props. - props.children
Element
: – The child components to render.
Returns
Component|null
: The rendered child components or null if page attributes are not supported.
PageAttributesOrder
Renders the Page Attributes Order component. A number input in an editor interface for setting the order of a given page. The component is now not used in core but was kept for backward compatibility.
Returns
Component
: The component to be rendered.
PageAttributesPanel
Renders the Page Attributes Panel component.
Returns
Component
: The component to be rendered.
PageAttributesParent
Renders the Page Attributes Parent component. A dropdown menu in an editor interface for selecting the parent page of a given page.
Returns
Component|null
: The component to be rendered. Return null if post type is not hierarchical.
PageTemplate
Provides a dropdown menu for selecting and managing post templates.
The dropdown menu includes a button for toggling the menu, a list of available templates, and options for creating and editing templates.
Returns
JSX.Element
: The rendered ClassicThemeControl component.
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.
PluginMoreMenuItem
Renders a menu item in Plugins
group in More Menu
drop down, and can be used to as a button or link depending on the props provided. The text within the component appears as the menu item label.
Usage
// Using ES5 syntax
var __ = wp.i18n.__;
var PluginMoreMenuItem = wp.editor.PluginMoreMenuItem;
var moreIcon = wp.element.createElement( 'svg' ); //... svg element.
function onButtonClick() {
alert( 'Button clicked.' );
}
function MyButtonMoreMenuItem() {
return wp.element.createElement(
PluginMoreMenuItem,
{
icon: moreIcon,
onClick: onButtonClick,
},
__( 'My button title' )
);
}
// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PluginMoreMenuItem } from '@wordpress/editor';
import { more } from '@wordpress/icons';
function onButtonClick() {
alert( 'Button clicked.' );
}
const MyButtonMoreMenuItem = () => (
<PluginMoreMenuItem icon={ more } onClick={ onButtonClick }>
{ __( 'My button title' ) }
</PluginMoreMenuItem>
);
Parameters
- props
Object
: Component properties. - props.href
[string]
: Whenhref
is provided then the menu item is represented as an anchor rather than button. It corresponds to thehref
attribute of the anchor. - props.icon
[WPBlockTypeIconRender]
: The Dashicon icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. - props.onClick
[Function]
: The callback function to be executed when the user clicks the menu item. - props.other
[...*]
: Any additional props are passed through to the underlying Button component.
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/editor';
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.
PluginPostStatusInfo
Renders a row in the Summary panel of the Document sidebar. It should be noted that this is named and implemented around the function it serves and not its location, which may change in future iterations.
Usage
// Using ES5 syntax
var __ = wp.i18n.__;
var PluginPostStatusInfo = wp.editor.PluginPostStatusInfo;
function MyPluginPostStatusInfo() {
return React.createElement(
PluginPostStatusInfo,
{
className: 'my-plugin-post-status-info',
},
__( 'My post status info' )
);
}
// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PluginPostStatusInfo } from '@wordpress/editor';
const MyPluginPostStatusInfo = () => (
<PluginPostStatusInfo className="my-plugin-post-status-info">
{ __( 'My post status info' ) }
</PluginPostStatusInfo>
);
Parameters
- props
Object
: Component properties. - props.className
[string]
: An optional class name added to the row. - 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/editor';
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.
PluginPreviewMenuItem
Renders a menu item in the Preview dropdown, which can be used as a button or link depending on the props provided. The text within the component appears as the menu item label.
Usage
import { __ } from '@wordpress/i18n';
import { PluginPreviewMenuItem } from '@wordpress/editor';
import { external } from '@wordpress/icons';
function onPreviewClick() {
// Handle preview action
}
const ExternalPreviewMenuItem = () => (
<PreviewDropdownMenuItem icon={ external } onClick={ onPreviewClick }>
{ __( 'Preview in new tab' ) }
</PreviewDropdownMenuItem>
);
registerPlugin( 'external-preview-menu-item', {
render: ExternalPreviewMenuItem,
} );
Parameters
- props
Object
: Component properties. - props.href
[string]
: Whenhref
is provided, the menu item is rendered as an anchor instead of a button. It corresponds to thehref
attribute of the anchor. - props.icon
[WPBlockTypeIconRender]
: The icon to be rendered to the left of the menu item label. Can be a Dashicon slug or an SVG WP element. - props.onClick
[Function]
: The callback function to be executed when the user clicks the menu item. - props.other
[...*]
: Any additional props are passed through to the underlying MenuItem component.
Returns
Component
: The rendered menu item component.
PluginSidebar
Renders a sidebar when activated. The contents within the PluginSidebar
will appear as content within the sidebar. It also automatically renders a corresponding PluginSidebarMenuItem
component when isPinnable
flag is set to true
. If you wish to display the sidebar, you can with use the PluginSidebarMoreMenuItem
component or the wp.data.dispatch
API:
wp.data
.dispatch( 'core/edit-post' )
.openGeneralSidebar( 'plugin-name/sidebar-name' );
Related
- PluginSidebarMoreMenuItem
Usage
// Using ES5 syntax
var __ = wp.i18n.__;
var el = React.createElement;
var PanelBody = wp.components.PanelBody;
var PluginSidebar = wp.editor.PluginSidebar;
var moreIcon = React.createElement( 'svg' ); //... svg element.
function MyPluginSidebar() {
return el(
PluginSidebar,
{
name: 'my-sidebar',
title: 'My sidebar title',
icon: moreIcon,
},
el( PanelBody, {}, __( 'My sidebar content' ) )
);
}
// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PanelBody } from '@wordpress/components';
import { PluginSidebar } from '@wordpress/editor';
import { more } from '@wordpress/icons';
const MyPluginSidebar = () => (
<PluginSidebar name="my-sidebar" title="My sidebar title" icon={ more }>
<PanelBody>{ __( 'My sidebar content' ) }</PanelBody>
</PluginSidebar>
);
Parameters
- props
Object
: Element props. - props.name
string
: A string identifying the sidebar. Must be unique for every sidebar registered within the scope of your plugin. - props.className
[string]
: An optional class name added to the sidebar body. - props.title
string
: Title displayed at the top of the sidebar. - props.isPinnable
[boolean]
: Whether to allow to pin sidebar to the toolbar. When set totrue
it also automatically renders a corresponding menu item. - props.icon
[WPBlockTypeIconRender]
: The Dashicon icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar.
PluginSidebarMoreMenuItem
Renders a menu item in Plugins
group in More Menu
drop down, and can be used to activate the corresponding PluginSidebar
component. The text within the component appears as the menu item label.
Usage
// Using ES5 syntax
var __ = wp.i18n.__;
var PluginSidebarMoreMenuItem = wp.editor.PluginSidebarMoreMenuItem;
var moreIcon = React.createElement( 'svg' ); //... svg element.
function MySidebarMoreMenuItem() {
return React.createElement(
PluginSidebarMoreMenuItem,
{
target: 'my-sidebar',
icon: moreIcon,
},
__( 'My sidebar title' )
);
}
// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PluginSidebarMoreMenuItem } from '@wordpress/editor';
import { more } from '@wordpress/icons';
const MySidebarMoreMenuItem = () => (
<PluginSidebarMoreMenuItem target="my-sidebar" icon={ more }>
{ __( 'My sidebar title' ) }
</PluginSidebarMoreMenuItem>
);
Parameters
- props
Object
: Component props. - props.target
string
: A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as thename
prop you have given to that sidebar. - props.icon
[WPBlockTypeIconRender]
: The Dashicon icon slug string, or an SVG WP element, to be rendered to the left of the menu item label.
Returns
Component
: The component to be rendered.
PostAuthor
Renders the component for selecting the post author.
Returns
Component
: The component to be rendered.
PostAuthorCheck
Wrapper component that renders its children only if the post type supports the author.
Parameters
- props
Object
: The component props. - props.children
Element
: Children to be rendered.
Returns
Component|null
: The component to be rendered. Returnnull
if the post type doesn’t supports the author or if there are no authors available.
PostAuthorPanel
Renders the Post Author Panel component.
Returns
Component
: The component to be rendered.
PostComments
A form for managing comment status.
Returns
JSX.Element
: The rendered PostComments component.
PostDiscussionPanel
This component allows to update comment and pingback settings for the current post. Internally there are checks whether the current post has support for the above and if the discussion-panel
panel is enabled.
Returns
JSX.Element|null
: The rendered PostDiscussionPanel component.
PostExcerpt
Renders an editable textarea for the post excerpt. Templates, template parts and patterns use the excerpt
field as a description semantically. Additionally templates and template parts override the excerpt
field as description
in REST API. So this component handles proper labeling and updating the edited entity.
Parameters
- props
Object
: – Component props. - props.hideLabelFromVision
[boolean]
: – Whether to visually hide the textarea’s label. - props.updateOnBlur
[boolean]
: – Whether to update the post on change or use local state and update on blur.
PostExcerptCheck
Component for checking if the post type supports the excerpt field.
Parameters
- props
Object
: Props. - props.children
Element
: Children to be rendered.
Returns
Component
: The component to be rendered.
PostExcerptPanel
Is rendered if the post type supports excerpts and allows editing the excerpt.
Returns
JSX.Element
: The rendered PostExcerptPanel component.
PostFeaturedImage
Renders the component for managing the featured image of a post.
Parameters
- props
Object
: Props. - props.currentPostId
number
: ID of the current post. - props.featuredImageId
number
: ID of the featured image. - props.onUpdateImage
Function
: Function to call when the image is updated. - props.onRemoveImage
Function
: Function to call when the image is removed. - props.media
Object
: The media object representing the featured image. - props.postType
string
: Post type. - props.noticeUI
Element
: UI for displaying notices. - props.noticeOperations
Object
: Operations for managing notices.
Returns
Element
: Component to be rendered .
PostFeaturedImageCheck
Wrapper component that renders its children only if the post type supports a featured image and the theme supports post thumbnails.
Parameters
- props
Object
: Props. - props.children
Element
: Children to be rendered.
Returns
Component
: The component to be rendered.
PostFeaturedImagePanel
Renders the panel for the post featured image.
Parameters
- props
Object
: Props. - props.withPanelBody
boolean
: Whether to include the panel body. Default true.
Returns
Component|null
: The component to be rendered. Return Null if the editor panel is disabled for featured image.
PostFormat
PostFormat
a component that allows changing the post format while also providing a suggestion for the current post.
Usage
<PostFormat />
Returns
JSX.Element
: The rendered PostFormat component.
PostFormatCheck
Component check if there are any post formats.
Parameters
- props
Object
: The component props. - props.children
Element
: The child elements to render.
Returns
Component|null
: The rendered component or null if post formats are disabled.
PostLastRevision
Renders the component for displaying the last revision of a post.
Returns
Component
: The component to be rendered.
PostLastRevisionCheck
Wrapper component that renders its children if the post has more than one revision.
Parameters
- props
Object
: Props. - props.children
Element
: Children to be rendered.
Returns
Component|null
: Rendered child components if post has more than one revision, otherwise null.
PostLastRevisionPanel
Renders the panel for displaying the last revision of a post.
Returns
Component
: The component to be rendered.
PostLockedModal
A modal component that is displayed when a post is locked for editing by another user. The modal provides information about the lock status and options to take over or exit the editor.
Returns
JSX.Element|null
: The rendered PostLockedModal component.
PostPendingStatus
A component for displaying and toggling the pending status of a post.
Returns
JSX.Element
: The rendered component.
PostPendingStatusCheck
This component checks the publishing status of the current post. If the post is already published or the user doesn’t have the capability to publish, it returns null.
Parameters
- props
Object
: Component properties. - props.children
Element
: Children to be rendered.
Returns
JSX.Element|null
: The rendered child elements or null if the post is already published or the user doesn’t have the capability to publish.
PostPingbacks
Renders a control for enabling or disabling pingbacks and trackbacks in a WordPress post.
PostPreviewButton
Renders a button that opens a new window or tab for the preview, writes the interstitial message to this window, and then navigates to the actual preview link. The button is not rendered if the post is not viewable and disabled if the post is not saveable.
Parameters
- props
Object
: The component props. - props.className
string
: The class name for the button. - props.textContent
string
: The text content for the button. - props.forceIsAutosaveable
boolean
: Whether to force autosave. - props.role
string
: The role attribute for the button. - props.onPreview
Function
: The callback function for preview event.
Returns
JSX.Element|null
: The rendered button component.
PostPublishButton
Renders the publish button.
PostPublishButtonLabel
Renders the label for the publish button.
Returns
string
: The label for the publish button.
PostPublishPanel
Renders a panel for publishing a post.
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
Renders the PostSchedule component. It allows the user to schedule a post.
Parameters
- props
Object
: Props. - props.onClose
Function
: Function to close the component.
Returns
Component
: The component to be rendered.
PostScheduleCheck
Wrapper component that renders its children only if post has a publish action.
Parameters
- props
Object
: Props. - props.children
Element
: Children to be rendered.
Returns
Component
: – The component to be rendered or null if there is no publish action.
PostScheduleLabel
Renders the PostScheduleLabel component.
Parameters
- props
Object
: Props.
Returns
Component
: The component to be rendered.
PostSchedulePanel
Renders the Post Schedule Panel component.
Returns
Component
: The component to be rendered.
PostSlug
Renders the PostSlug component. It provide a control for editing the post slug.
Returns
Component
: The component to be rendered.
PostSlugCheck
Wrapper component that renders its children only if the post type supports the slug.
Parameters
- props
Object
: Props. - props.children
Element
: Children to be rendered.
Returns
Component
: The component to be rendered.
PostSticky
Renders the PostSticky component. It provides a checkbox control for the sticky post feature.
Returns
Component
: The component to be rendered.
PostStickyCheck
Wrapper component that renders its children only if post has a sticky action.
Parameters
- props
Object
: Props. - props.children
Element
: Children to be rendered.
Returns
Component
: The component to be rendered or null if post type is not ‘post’ or hasStickyAction is false.
PostSwitchToDraftButton
Renders a button component that allows the user to switch a post to draft status.
Returns
JSX.Element
: The rendered component.
PostSyncStatus
Renders the sync status of a post.
Returns
JSX.Element|null
: The rendered sync status component.
PostTaxonomies
Renders the taxonomies associated with a post.
Parameters
- props
Object
: The component props. - props.taxonomyWrapper
Function
: The wrapper function for each taxonomy component.
Returns
Array
: An array of JSX elements representing the visible taxonomies.
PostTaxonomiesCheck
Renders the children components only if the current post type has taxonomies.
Parameters
- props
Object
: The component props. - props.children
Element
: The children components to render.
Returns
Component|null
: The rendered children components or null if the current post type has no taxonomies.
PostTaxonomiesFlatTermSelector
Renders a flat term selector component.
Parameters
- props
Object
: The component props. - props.slug
string
: The slug of the taxonomy. - props.__nextHasNoMarginBottom
boolean
: Start opting into the new margin-free styles that will become the default in a future version, currently scheduled to be WordPress 7.0. (The prop can be safely removed once this happens.)
Returns
JSX.Element
: The rendered flat term selector component.
PostTaxonomiesHierarchicalTermSelector
Hierarchical term selector.
Parameters
- props
Object
: Component props. - props.slug
string
: Taxonomy slug.
Returns
Element
: Hierarchical term selector component.
PostTaxonomiesPanel
Renders a panel for a specific taxonomy.
Parameters
- props
Object
: The component props. - props.taxonomy
Object
: The taxonomy object. - props.children
Element
: The child components.
Returns
Component
: The rendered taxonomy panel.
PostTemplatePanel
Displays the template controls based on the current editor settings and user permissions.
Returns
JSX.Element|null
: The rendered PostTemplatePanel component.
PostTextEditor
Displays the Post Text Editor along with content in Visual and Text mode.
Returns
JSX.Element|null
: The rendered PostTextEditor component.
PostTitle
Renders the PostTitle
component.
Parameters
- ___
Object
: Unused parameter. - forwardedRef
Element
: Forwarded ref for the component.
Returns
Component
: The rendered PostTitle component.
PostTitleRaw
Undocumented declaration.
PostTrash
Displays the Post Trash Button and Confirm Dialog in the Editor.
Parameters
- An
?{onActionPerformed: Object}
: object containing the onActionPerformed function.
Returns
JSX.Element|null
: The rendered PostTrash component.
PostTrashCheck
Wrapper component that renders its children only if the post can trashed.
Parameters
- props
Object
: – The component props. - props.children
Element
: – The child components to render.
Returns
Component|null
: The rendered child components or null if the post can not trashed.
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
Renders the PostURL
component.
Usage
<PostURL />
Parameters
- onClose
Function
: Callback function to be executed when the popover is closed.
Returns
Component
: The rendered PostURL component.
PostURLCheck
Check if the post URL is valid and visible.
Parameters
- props
Object
: The component props. - props.children
Element
: The child components.
Returns
Component|null
: The child components if the post URL is valid and visible, otherwise null.
PostURLLabel
Represents a label component for a post URL.
Returns
Component
: The PostURLLabel component.
PostURLPanel
Renders the PostURLPanel
component.
Returns
JSX.Element
: The rendered PostURLPanel component.
PostVisibility
Allows users to set the visibility of a post.
Parameters
- props
Object
: The component props. - props.onClose
Function
: Function to call when the popover is closed.
Returns
JSX.Element
: The rendered component.
PostVisibilityCheck
Determines if the current post can be edited (published) and passes this information to the provided render function.
Parameters
- props
Object
: The component props. - props.render
Function
: Function to render the component. Receives an object with acanEdit
property.
Returns
JSX.Element
: The rendered component.
PostVisibilityLabel
Returns the label for the current post visibility setting.
Returns
string
: Post visibility label.
privateApis
Undocumented declaration.
registerEntityAction
Registers a new DataViews action.
This is an experimental API and is subject to change. it’s only available in the Gutenberg plugin for now.
Parameters
- kind
string
: Entity kind. - name
string
: Entity name. - config
Action
: Action configuration.
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
Type
Object
storeConfig
Post editor data store configuration.
Related
Type
Object
TableOfContents
Renders a table of contents component.
Parameters
- props
Object
: The component props. - props.hasOutlineItemsDisabled
boolean
: Whether outline items are disabled. - props.repositionDropdown
boolean
: Whether to reposition the dropdown. - ref
Element.ref
: The component’s ref.
Returns
JSX.Element
: The rendered table of contents component.
TextEditorGlobalKeyboardShortcuts
Handles the keyboard shortcuts for the editor.
It provides functionality for various keyboard shortcuts such as toggling editor mode, toggling distraction-free mode, undo/redo, saving the post, toggling list view, and toggling the sidebar.
ThemeSupportCheck
Checks if the current theme supports specific features and renders the children if supported.
Parameters
- props
Object
: The component props. - props.children
Element
: The children to render if the theme supports the specified features. - props.supportKeys
string|string[]
: The key(s) of the theme support(s) to check.
Returns
JSX.Element|null
: The rendered children if the theme supports the specified features, otherwise null.
TimeToRead
Component for showing Time To Read in Content.
Returns
JSX.Element
: The rendered TimeToRead component.
transformStyles
Undocumented declaration.
unregisterEntityAction
Unregisters a DataViews action.
This is an experimental API and is subject to change. it’s only available in the Gutenberg plugin for now.
Parameters
- kind
string
: Entity kind. - name
string
: Entity name. - actionId
string
: Action ID.
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
Custom hook that determines if any entities are dirty (edited) and provides a way to manage selected/unselected entities.
Returns
Object
: An object containing the following properties: – dirtyEntityRecords: An array of dirty entity records. – isDirty: A boolean indicating if there are any dirty entity records. – setUnselectedEntities: A function to set the unselected entities. – unselectedEntities: An array of unselected entities.
usePostScheduleLabel
Custom hook to get the label for post schedule.
Parameters
- options
Object
: Options for the hook. - options.full
boolean
: Whether to get the full label or not. Default is false.
Returns
string
: The label for post schedule.
usePostURLLabel
Custom hook to get the label for the post URL.
Returns
string
: The filtered and decoded post URL label.
usePostVisibilityLabel
Get the label for the current post visibility setting.
Returns
string
: Post visibility label.
userAutocompleter
A user mentions completer.
Type
WPCompleter
VisualEditorGlobalKeyboardShortcuts
Handles the keyboard shortcuts for the editor.
It provides functionality for various keyboard shortcuts such as toggling editor mode, toggling distraction-free mode, undo/redo, saving the post, toggling list view, and toggling the sidebar.
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
Renders the word count of the post content.
Returns
JSX.Element|null
: The rendered WordCount component.
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.