Miss any of our Open RFC calls?Watch the recordings here! »

@wordpress/block-editor

5.1.3 • Public • Published

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 ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.

Usage

import {
    BlockEditorProvider,
    BlockList,
    WritingFlow,
    ObserveTyping
} from '@wordpress/block-editor';
import { SlotFillProvider, Popover } from '@wordpress/components';
import { useState } from '@wordpress/element';
 
function MyEditorComponent () {
    const [ blocks, updateBlocks ] = useState( [] );
 
    return (
        <BlockEditorProvider
            value={ blocks }
            onInput={ ( blocks ) => updateBlocks( blocks ) }
            onChange={ ( blocks ) => updateBlocks( blocks ) }
        >
            <SlotFillProvider>
                <Popover.Slot name="block-toolbar" />
                <WritingFlow>
                    <ObserveTyping>
                        <BlockList />
                    </ObserveTyping>
                </WritingFlow>
                <Popover.Slot />
            </SlotFillProvider>
        </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 Popover.Slot with the name="block-toolbar" prop 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

# AlignmentToolbar

Undocumented declaration.

# Autocomplete

Related

# BlockAlignmentToolbar

Undocumented declaration.

# BlockBreadcrumb

Block breadcrumb component, displaying the hierarchy of the current block selection as a breadcrumb.

Returns

  • WPElement: Block Breadcrumb.

# BlockColorsStyleSelector

Undocumented declaration.

# BlockContextProvider

Component which merges passed value with current consumed block context.

Related

Parameters

  • props BlockContextProviderProps:

# BlockControls

Undocumented declaration.

# BlockEdit

Undocumented declaration.

# BlockEditorKeyboardShortcuts

Undocumented declaration.

# BlockEditorProvider

Undocumented declaration.

# BlockFormatControls

Undocumented declaration.

# BlockIcon

Undocumented declaration.

# BlockInspector

Undocumented declaration.

# BlockList

Undocumented declaration.

# BlockMover

Undocumented declaration.

# BlockNavigationDropdown

Undocumented declaration.

# BlockPreview

BlockPreview renders a preview of a block or array of blocks.

Related

Parameters

  • preview Object: options for how the preview should be shown
  • preview.blocks (Array|Object): A block instance (object) or an array of blocks to be previewed.
  • preview.viewportWidth number: Width of the preview container in pixels. Controls at what size the blocks will be rendered inside the preview. Default: 700.

Returns

  • WPComponent: The component to be rendered.

# BlockSelectionClearer

Undocumented declaration.

# BlockSettingsMenu

Undocumented declaration.

# BlockSettingsMenuControls

Related

# BlockTitle

Renders the block's configured title as a string, or empty if the title cannot be determined.

Usage

<BlockTitle clientId="afd1cb17-2c08-4e7a-91be-007ba7ddc3a1" />

Parameters

  • props Object:
  • props.clientId string: Client ID of block.

Returns

  • ?string: Block title.

# BlockToolbar

Undocumented declaration.

# BlockVerticalAlignmentToolbar

Related

# ButtonBlockerAppender

Related

# ColorPalette

Undocumented declaration.

# ColorPaletteControl

Undocumented declaration.

# ContrastChecker

Undocumented declaration.

# CopyHandler

Undocumented declaration.

# createCustomColorsHOC

A higher-order component factory for creating a 'withCustomColors' HOC, which handles color logic for class generation color value, retrieval and color attribute setting.

Use this higher-order component to work with a custom set of colors.

Usage

const CUSTOM_COLORS = [ { name: 'Red', slug: 'red', color: '#ff0000' }, { name: 'Blue', slug: 'blue', color: '#0000ff' } ];
const withCustomColors = createCustomColorsHOC( CUSTOM_COLORS );
// ...
export default compose(
    withCustomColors( 'backgroundColor', 'borderColor' ),
    MyColorfulComponent,
);

Parameters

  • colorsArray Array: The array of color objects (name, slug, color, etc... ).

Returns

  • Function: Higher-order component.

# DefaultBlockAppender

Undocumented declaration.

# FontSizePicker

Undocumented declaration.

# getColorClassName

Returns a class based on the context a color is being used and its slug.

Parameters

  • colorContextName string: Context/place where color is being used e.g: background, text etc...
  • colorSlug string: Slug of the color.

Returns

  • ?string: String with the class corresponding to the color in the provided context. Returns undefined if either colorContextName or colorSlug are not provided.

# getColorObjectByAttributeValues

Provided an array of color objects as set by the theme or by the editor defaults, and the values of the defined color or custom color returns a color object describing the color.

Parameters

  • colors Array: Array of color objects as set by the theme or by the editor defaults.
  • definedColor ?string: A string containing the color slug.
  • customColor ?string: A string containing the customColor value.

Returns

  • ?Object: If definedColor is passed and the name is found in colors, the color object exactly as set by the theme or editor defaults is returned. Otherwise, an object that just sets the color is defined.

# getColorObjectByColorValue

Provided an array of color objects as set by the theme or by the editor defaults, and a color value returns the color object matching that value or undefined.

Parameters

  • colors Array: Array of color objects as set by the theme or by the editor defaults.
  • colorValue ?string: A string containing the color value.

Returns

  • ?Object: Color object included in the colors array whose color property equals colorValue. Returns undefined if no color object matches this requirement.

# getFontSize

Returns the font size object based on an array of named font sizes and the namedFontSize and customFontSize values. If namedFontSize is undefined or not found in fontSizes an object with just the size value based on customFontSize is returned.

Parameters

  • fontSizes Array: Array of font size objects containing at least the "name" and "size" values as properties.
  • fontSizeAttribute ?string: Content of the font size attribute (slug).
  • customFontSizeAttribute ?number: Contents of the custom font size attribute (value).

Returns

  • ?Object: If fontSizeAttribute is set and an equal slug is found in fontSizes it returns the font size object for that slug. Otherwise, an object with just the size value based on customFontSize is returned.

# getFontSizeClass

Returns a class based on fontSizeName.

Parameters

  • fontSizeSlug string: Slug of the fontSize.

Returns

  • string: String with the class corresponding to the fontSize passed. The class is generated by appending 'has-' followed by fontSizeSlug in kebabCase and ending with '-font-size'.

# getFontSizeObjectByValue

Returns the corresponding font size object for a given value.

Parameters

  • fontSizes Array: Array of font size objects.
  • value number: Font size value.

Returns

  • Object: Font size object.

# getGradientSlugByValue

Retrieves the gradient slug per slug.

Parameters

  • gradients Array: Gradient Palette
  • value string: Gradient value

Returns

  • string: Gradient slug.

# getGradientValueBySlug

Retrieves the gradient value per slug.

Parameters

  • gradients Array: Gradient Palette
  • slug string: Gradient slug

Returns

  • string: Gradient value.

# InnerBlocks

Related

# Inserter

Undocumented declaration.

# InspectorAdvancedControls

Related

# InspectorControls

Related

# LineHeightControl

Undocumented declaration.

# MediaPlaceholder

Related

# MediaReplaceFlow

Undocumented declaration.

# MediaUpload

Related

# MediaUploadCheck

Related

# MultiSelectScrollIntoView

Scrolls the multi block selection end into view if not in view already. This is important to do after selection by keyboard.

# NavigableToolbar

Undocumented declaration.

# ObserveTyping

Related

# PanelColorSettings

Undocumented declaration.

# PlainText

Related

# PreserveScrollInReorder

Undocumented declaration.

# RichText

Related

# RichTextShortcut

Undocumented declaration.

# RichTextToolbarButton

Undocumented declaration.

# SETTINGS_DEFAULTS

The default editor settings

Type Definition

  • SETTINGS_DEFAULT Object

Properties

  • alignWide boolean: Enable/Disable Wide/Full Alignments
  • availableLegacyWidgets Array: Array of objects representing the legacy widgets available.
  • imageEditing boolean: Image Editing settings set to false to disable.
  • imageSizes Array: Available image sizes
  • maxWidth number: Max width to constraint resizing
  • allowedBlockTypes (boolean|Array): Allowed block types
  • hasFixedToolbar boolean: Whether or not the editor toolbar is fixed
  • focusMode boolean: Whether the focus mode is enabled or not
  • styles Array: Editor Styles
  • isRTL boolean: Whether the editor is in RTL mode
  • keepCaretInsideBlock boolean: Whether caret should move between blocks in edit mode
  • bodyPlaceholder string: Empty post placeholder
  • titlePlaceholder string: Empty title placeholder
  • codeEditingEnabled boolean: Whether or not the user can switch to the code editor
  • __experimentalCanUserUseUnfilteredHTML boolean: Whether the user should be able to use unfiltered HTML or the HTML should be filtered e.g., to remove elements considered insecure like iframes.
  • __experimentalBlockDirectory boolean: Whether the user has enabled the Block Directory
  • __experimentalEnableFullSiteEditing boolean: Whether the user has enabled Full Site Editing
  • __experimentalEnableFullSiteEditingDemo boolean: Whether the user has enabled Full Site Editing Demo Templates
  • __experimentalBlockPatterns Array: Array of objects representing the block patterns
  • __experimentalBlockPatternCategories Array: Array of objects representing the block pattern categories

# SkipToSelectedBlock

Undocumented declaration.

# storeConfig

Block editor data store configuration.

Related

Type

  • Object

# ToolSelector

Undocumented declaration.

# transformStyles

Applies a series of CSS rule transforms to wrap selectors inside a given class and/or rewrite URLs depending on the parameters passed.

Parameters

  • styles Array: CSS rules.
  • wrapperClassName string: Wrapper Class Name.

Returns

  • Array: converted rules.

# Typewriter

Ensures that the text selection keeps the same vertical distance from the viewport during keyboard events within this component. The vertical distance can vary. It is the last clicked or scrolled to position.

# URLInput

Related

# URLInputButton

Related

# URLPopover

Related

# useBlockEditContext

Undocumented declaration.

# useBlockProps

This hook is used to lightly mark an element as a block element. The element should be the outermost element of a block. Call this hook and pass the returned props to the element to mark as a block. If you define a ref for the element, it is important to pass the ref to this hook, which the hook in turn will pass to the component through the props it returns. Optionally, you can also pass any other props through this hook, and they will be merged and returned.

Parameters

  • props Object: Optional. Props to pass to the element. Must contain the ref if one is defined.
  • options Object: Options for internal use only.
  • options.__unstableIsHtml boolean:

Returns

  • Object: Props to pass to the element to mark as a block.

# validateThemeColors

Given an array of theme colors checks colors for validity

Parameters

  • colors Array: The array of theme colors

Returns

  • Array: The array of valid theme colors or the default colors

# validateThemeGradients

Given an array of theme gradients checks gradients for validity

Parameters

  • gradients Array: The array of theme gradients

Returns

  • Array: The array of valid theme gradients or the default gradients

# Warning

Related

# withColorContext

Undocumented declaration.

# withColors

A higher-order component, which handles color logic for class generation color value, retrieval and color attribute setting.

For use with the default editor/theme color palette.

Usage

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

Parameters

  • colorTypes ...(Object|string): The arguments can be strings or objects. If the argument is an object, it should contain the color attribute name as key and the color context as value. If the argument is a string the value should be the color attribute name, the color context is computed by applying a kebab case transform to the value. Color context represents the context/place where the color is going to be used. The class name of the color is generated using 'has' followed by the color name and ending with the color context all in kebab case e.g: has-green-background-color.

Returns

  • Function: Higher-order component.

# withFontSizes

Higher-order component, which handles font size logic for class generation, font size value retrieval, and font size change handling.

Parameters

  • fontSizeNames ...(Object|string): The arguments should all be strings. Each string contains the font size attribute name e.g: 'fontSize'.

Returns

  • Function: Higher-order component.

# WritingFlow

Handles selection and navigation across blocks. This component should be wrapped around BlockList.

Parameters

  • props Object: Component properties.
  • props.children WPElement: Children to be rendered.



Code is Poetry.

Install

npm i @wordpress/block-editor

DownloadsWeekly Downloads

18,671

Version

5.1.3

License

GPL-2.0-or-later

Unpacked Size

8.24 MB

Total Files

1786

Last publish

Collaborators

  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar