Design System is here - Read the release post

Learn GeneratePress

Developers

Editor: inspector controls and panels

JavaScript hooks for adding to or changing the controls in the block editor: the block inspector, the style panels, individual controls and presets, and the GenerateBlocks editor sidebar. These are wp.hooks filters and actions. Add them with wp.hooks.addFilter() or wp.hooks.addAction() in a script that loads in the block editor, after wp-hooks and the GenerateBlocks editor scripts.

To control who can see or edit these controls, see Editor Access. For block output and appenders, see Editor: block attributes, appenders and preview.

Jump to

Inspector and style panels

Each block’s style panels are wrapped in three nested “slot” filters: generateblocks.editor.blockControls wraps all of a block’s panels, generateblocks.editor.panel wraps each panel, and generateblocks.panel.{panelId} wraps one named panel. Each runs generateblocks.editor.panel.beforeFilters first, so you can prepare before any of them filter.

generateblocks.editor.inspectorControls

GB Free — GenerateBlocks Pro also uses it.

The generateblocks.editor.inspectorControls filter replaces the controls in a block’s default inspector area. It only runs for areas that can be replaced.

Parameters: content (undefined by default), props (object with area, defaultControls, replaceable, selectedBlock and the props the block passed in, such as clientId). selectedBlock is the selected block object from the block editor store (getSelectedBlock(), with name, clientId, attributes and so on), or null when the block isn’t selected. Default: undefined, which renders the default controls. Return an element to render it instead. Return props.defaultControls inside your element to keep the defaults.

const { createElement, Fragment } = wp.element;
const { PanelBody } = wp.components;

wp.hooks.addFilter(
    'generateblocks.editor.inspectorControls',
    'my-plugin/inspector-controls',
    ( content, props ) => {
        if ( 'generateblocks/text' !== props.selectedBlock?.name ) {
            return content;
        }

        return createElement(
            Fragment,
            null,
            createElement( PanelBody, { title: 'My panel' }, 'My controls' ),
            props.defaultControls
        );
    }
);

Related: generateblocks.editor.areInspectorControlsDisabled Guide: The Block Editor

generateblocks.editor.blockControls

GB Free

The generateblocks.editor.blockControls filter wraps all the style panels of a block, so you can add panels before or after them or replace them.

Parameters: content (the block’s panels), props (object with name, blockName, getStyleValue, onStyleChange, currentAtRule, attributes and setAttributes). Default: the block’s panels unchanged.

const { createElement, Fragment } = wp.element;

wp.hooks.addFilter(
    'generateblocks.editor.blockControls',
    'my-plugin/block-controls',
    ( content, props ) => {
        if ( 'generateblocks/text' !== props.blockName ) {
            return content;
        }

        return createElement( Fragment, null, content, createElement( 'p', null, 'Added after the Text block panels.' ) );
    }
);

Related: generateblocks.editor.panel, generateblocks.editor.panel.beforeFilters Guide: The Blocks Styles

generateblocks.editor.panel

GB Free

The generateblocks.editor.panel filter wraps every style panel, before the panel’s own contents.

Parameters: content (the panel), props (object with name, blockName, state, panelRef and the panel’s own props, such as id and title). Default: the panel unchanged.

wp.hooks.addFilter(
    'generateblocks.editor.panel',
    'my-plugin/panel',
    ( content, props ) => content
);

Related: generateblocks.panel.{panelId}, generateblocks.editor.panelContents Guide: The Blocks Styles

generateblocks.panel.{panelId}

GB Free

The generateblocks.panel.{panelId} filter wraps one named panel. Replace {panelId} with the panel’s ID, for example generateblocks.panel.link-destination.

Parameters: content (the panel), props (object with name, props, the panel’s own props, and state). Default: the panel unchanged.

Panel IDs found in the compiled editor scripts: block-list, carousel-autoplay, carousel-effects, carousel-layout, carousel-navigation, carousel-responsive, design, grid, helper-classes, icon, inline-background-image, link-destination, orderby, query-parameters, settings, shape and shapes. Which panels a block has depends on the block.

wp.hooks.addFilter(
    'generateblocks.panel.link-destination',
    'my-plugin/link-destination-panel',
    ( content, props ) => content
);

Related: generateblocks.editor.panel Guide: The Blocks Styles

generateblocks.editor.panel.beforeFilters

GB Free

The generateblocks.editor.panel.beforeFilters action fires each time a slot filter is about to run, before generateblocks.editor.blockControls, generateblocks.editor.panel and generateblocks.panel.{panelId} filter their content.

Parameters: props (the same props the slot filter receives). Default: none. It is an action, so it returns nothing.

wp.hooks.addAction(
    'generateblocks.editor.panel.beforeFilters',
    'my-plugin/before-filters',
    ( props ) => {
        // Prepare anything your filters need.
    }
);

Related: generateblocks.editor.blockControls Guide: The Blocks Styles

generateblocks.editor.showPanel

GB Free

The generateblocks.editor.showPanel filter chooses whether a style panel is shown.

Parameters: show (bool), panelId (string, the panel’s ID), props (the panel’s props). Default: the panel’s own showPanel setting, which is true unless the panel sets it.

wp.hooks.addFilter(
    'generateblocks.editor.showPanel',
    'my-plugin/show-panel',
    ( show, panelId ) => ( 'link-destination' === panelId ? false : show )
);

Related: generateblocks.editor.panelContents Guide: The Blocks Styles

generateblocks.editor.panelContents

GB Free

The generateblocks.editor.panelContents filter changes what a style panel contains.

Parameters: content (the panel’s controls), panelId (string), props (the panel’s props). Default: the panel’s controls unchanged.

const { createElement, Fragment } = wp.element;

wp.hooks.addFilter(
    'generateblocks.editor.panelContents',
    'my-plugin/panel-contents',
    ( content, panelId ) => {
        if ( 'settings' !== panelId ) {
            return content;
        }

        return createElement( Fragment, null, content, createElement( 'p', null, 'Added to the Settings panel.' ) );
    }
);

Related: generateblocks.editor.showPanel, generateblocks.blockSettings.openPanel Guide: The Blocks Styles

generateblocks.blockSettings.openPanel

GB Free — GenerateBlocks Pro uses it to add Device Visibility to the Settings panel.

The generateblocks.blockSettings.openPanel filter changes the contents of an open (always visible) panel in the block settings.

Parameters: content (the panel’s children), props (object with panelId, title, dropdownOptions, shouldRender, className, and, for style panels, getStyleValue and onStyleChange). Default: the panel’s children unchanged.

const { createElement, Fragment } = wp.element;

wp.hooks.addFilter(
    'generateblocks.blockSettings.openPanel',
    'my-plugin/open-panel',
    ( content, { panelId } ) => {
        if ( 'settings' !== panelId ) {
            return content;
        }

        return createElement( Fragment, null, content, createElement( 'p', null, 'Added to the Settings panel.' ) );
    }
);

Related: generateblocks-pro.deviceVisibilityOptions Guide: The Blocks Settings

generateblocks.blockSettings.afterImageUrlControls

GB Free

The generateblocks.blockSettings.afterImageUrlControls filter adds controls after the Image URL control in the Media block.

Parameters: content (null by default), attributes (the Media block’s attributes). Default: null.

const { createElement } = wp.element;

wp.hooks.addFilter(
    'generateblocks.blockSettings.afterImageUrlControls',
    'my-plugin/after-image-url',
    ( content, attributes ) => createElement( 'p', null, 'Added after the Image URL control.' )
);

Related: generateblocks.media.imageAttributes Guide: The Blocks Settings

Back to top

Controls and presets

generateblocks.control.props

GB Free — GenerateBlocks Pro also uses it.

The generateblocks.control.props filter changes the props a style control receives before it renders.

Parameters: componentProps (the props that will be passed to the control), context (object with componentProps, props, capabilities, wrapperRef, label, labelProps, controlId, unusedProps, cssProp, searchKeywords, alwaysVisible and matchTypes). Default: componentProps unchanged.

wp.hooks.addFilter(
    'generateblocks.control.props',
    'my-plugin/control-props',
    ( componentProps, context ) => componentProps
);

Related: generateblocks.components.colorPalettes Guide: The Blocks Styles

generateblocks.components.colorPalettes

GB Free — GenerateBlocks Pro also uses it.

The generateblocks.components.colorPalettes filter changes the colour palettes offered in GenerateBlocks colour pickers.

Parameters: palettes (array, the palettes passed to the picker, or the site’s custom and theme palettes), props (the colour picker’s props, including cssProp, the CSS property being edited), defaultPalettes (array, the site’s custom and theme palettes). Default: the picker’s palettes, or the site’s custom and theme palettes when the picker doesn’t pass any.

The array must be all flat colours ({ name, color }) or all groups ({ name, colors: [ { name, color } ] }), not a mix. GenerateBlocks Pro’s Design Tokens use this filter and wrap flat palettes in a group before adding their own.

wp.hooks.addFilter(
    'generateblocks.components.colorPalettes',
    'my-plugin/color-palettes',
    ( palettes ) => {
        const isGrouped = ( entry ) => entry && Array.isArray( entry.colors );
        const brand = { name: 'Brand', colors: [ { name: 'Brand orange', color: '#ff5500' } ] };

        if ( palettes.every( isGrouped ) ) {
            return [ ...palettes, brand ];
        }

        return [ { name: 'Theme', colors: palettes }, brand ];
    }
);

Related: generateblocks.editor.gradientPresets Guide: The Blocks Styles

generateblocks.editor.gradientPresets

GB Free — GenerateBlocks Pro also uses it.

The generateblocks.editor.gradientPresets filter changes the gradient presets in the gradient control.

Parameters: presets (array of groups, each { name, gradients: [ { slug, gradient } ] }, where gradient is a CSS gradient string). Default: the presets passed to the control, unchanged.

wp.hooks.addFilter(
    'generateblocks.editor.gradientPresets',
    'my-plugin/gradient-presets',
    ( presets ) => [
        ...presets,
        {
            name: 'Brand',
            gradients: [
                { slug: 'brand-fade', gradient: 'linear-gradient(90deg, #ff5500, #ffaa00)' },
            ],
        },
    ]
);

Related: generateblocks.components.colorPalettes Guide: The Blocks Styles

generateblocks.editor.iconSVGSets

GB Free — GenerateBlocks Pro adds its custom SVG icons with it.

The generateblocks.editor.iconSVGSets filter changes the icon sets in the icon picker of the Text and Shape blocks. The Shape block’s divider shapes come from the PHP filter generateblocks_svg_shapes instead.

Parameters: sets (object, the icon sets, empty by default), context (object with the block’s attributes). Default: an empty object. Return an object that merges your sets with sets. Each set is keyed by a slug and has the shape { group, svgs: { [iconId]: { label, icon } } }, where icon is the SVG markup as a string. GenerateBlocks Pro adds the icons you save in its Asset Library this way.

wp.hooks.addFilter(
    'generateblocks.editor.iconSVGSets',
    'my-plugin/icon-sets',
    ( sets ) => ( {
        ...sets,
        brand: {
            group: 'Brand',
            svgs: {
                circle: {
                    label: 'Circle',
                    icon: '<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="10"/></svg>',
                },
            },
        },
    } )
);

Related: generateblocks_svg_shapes Guide: SVG Shapes & Icons

generateblocks-pro.deviceVisibilityOptions

GB Pro

The generateblocks-pro.deviceVisibilityOptions filter changes the Device Visibility toggles in the Settings panel.

Parameters: options (array of { label, ruleId }). Default: four options: Hide on Desktop (largeWidth), Hide on Tablet (mediumWidth), Hide on Tablet & Mobile (mediumSmallWidth) and Hide on Mobile (smallWidth).

ruleId is an at-rule ID from generateblocks.styles.defaultAtRules, which the styles builder turns into a media query. The built-in IDs are largeWidth (@media (min-width:1025px)), mediumWidth (@media (max-width:1024px) and (min-width:768px)), mediumSmallWidth (@media (max-width:1024px)), mediumLargeWidth (@media (min-width:768px)) and smallWidth (@media (max-width:767px)). Each toggle sets display to none !important for that at-rule.

wp.hooks.addFilter(
    'generateblocks-pro.deviceVisibilityOptions',
    'my-plugin/device-visibility',
    ( options ) => options.filter( ( option ) => 'largeWidth' !== option.ruleId )
);

Related: generateblocks.blockSettings.openPanel Guide: Device Visibility controls

Back to top

Editor sidebar

generateblocks.editor.sidebarHeader

GB Free

The generateblocks.editor.sidebarHeader filter changes the header of the GenerateBlocks editor sidebar.

Parameters: content (the header’s children), props (the header’s props). Default: the header’s children unchanged.

const { createElement, Fragment } = wp.element;

wp.hooks.addFilter(
    'generateblocks.editor.sidebarHeader',
    'my-plugin/sidebar-header',
    ( content ) => createElement( Fragment, null, content, createElement( 'span', null, 'My plugin' ) )
);

Related: generateblocks.editor.panel Guide: The Block Editor

Back to top