Client-Side block settings filtering in WordPress

WordPress’s block editor (Gutenberg) provides powerful customization capabilities through client-side filtering. This article explores how to curate the editor experience using the blockEditor.useSetting.before filter, introduced in WordPress 6.2.

Understanding Client-Side Filtering

The blockEditor.useSetting.before filter allows developers to modify block-level theme.json settings before the editor renders. Unlike server-side filters, this client-side approach offers greater control and contextual awareness.

Important Limitation: Styles Tab Only

It’s crucial to understand that the blockEditor.useSetting.before filter only affects settings in the “Styles” tab of the block inspector panel (where the colors/typography settings are). This filter cannot modify or hide settings in the “Settings” tab. To modify settings tab controls, you’ll need to use different approaches such as:

blocks.registerBlockType filter for modifying block supports during registration
editor.BlockEdit filter for modifying the block’s edit component
editor.BlockListBlock filter for modifying the block’s wrapper

This limitation exists because the filter is specifically designed to work with theme.json style settings, which correspond to the controls in the Styles tab.

Basic Setup

To get started, you’ll need to import the necessary WordPress dependencies:

const { select } = wp.data;
const { addFilter } = wp.hooks;
// or
import { select } from '@wordpress/data'
import { addFilter } from '@wordpress/hooks'

Filter Structure

The filter callback accepts four parameters:

settingValue: Current value of the block setting
settingName: Name of the block setting to modify
clientId: Unique identifier for the block
blockName: Name of the block type

Practical Example

Let’s look at a simple example that restricts colors settings for heading blocks inside group blocks:

const parentBlockName = 'core/group';
const childBlocksArray = [{
    name: 'core/heading',
    disabledSettings: {
        'color.background': false,
        'color.text': false,
    }
}];

// Cache select functions outside the filter callback
const { getBlockName, getBlockParents } = select('core/block-editor');

// Create a map for faster lookups
const childBlocksMap = new Map(childBlocksArray.map((block) => [block.name, block]))

addFilter(
    'blockEditor.useSetting.before',
    'block-curation-example/useSetting.before/heading-in-group',
    (settingValue, settingName, clientId, blockName) => {
        // Early return if block is not in our configuration
        const childBlock = childBlocksMap.get(blockName)
        if (!childBlock) {
           return settingValue
        }
        
        const blockParents = getBlockParents(clientId, true);
        const inGroup = blockParents.some(
            (ancestorId) => getBlockName(ancestorId) === parentBlockName
        );

        if (inGroup && childBlock.disabledSettings[settingName] === false) {
            return false;
        }

        return settingValue;
    }
);

This example demonstrates how to:

Define target blocks and their settings
Check if a block is inside a specific parent
Apply restrictions based on context

List of Filterable Settings

Here’s a non-exhaustive of settings you can filter:

Typography Settings

typography.fontFamilies.custom
typography.fontFamilies.default
typography.fontFamilies.theme
typography.fontSizes
typography.customFontSize
typography.fontStyle
typography.fontWeight
typography.letterSpacing
typography.lineHeight
typography.textAlign
typography.textDecoration
typography.textTransform
typography.writingMode

Color Settings

color.background
color.custom
color.customDuotone
color.customGradient
color.defaultDuotone
color.defaultGradients
color.defaultPalette
color.duotone.custom
color.duotone.default
color.duotone.theme
color.gradients.custom
color.gradients.default
color.gradients.theme
color.link
color.palette.custom
color.palette.default
color.palette.theme
color.text

Spacing Settings

spacing.margin
spacing.padding
spacing.blockGap
spacing.units

Border Settings

border.color
border.radius
border.style
border.width

Layout Settings

layout.contentSize
layout.wideSize
layout.allowCustomContent
layout.allowSizingOnChildren

Useful Links

Best Practices

Always check for block context before applying filters
Use meaningful namespaces for your filters
Keep performance in mind – avoid complex operations in the filter callback
Document your filters and their intended effects
Test thoroughly across different block combinations

Conclusion

Client-side filtering provides a powerful way to customize the WordPress block editor experience. By understanding and implementing these filters, you can create more focused and user-friendly editing experiences that align with your project’s needs.

Remember that the blockEditor.useSetting.before filter only works with settings that can be defined in theme.json, and it won’t generate new CSS variables. Always ensure that any modified settings are properly defined in your theme’s theme.json file.