WordPress provides Format API to add custom buttons in formatting toolbar to apply specific styles to the selected text. When a format is applied to a text selection, the text selection is wrapped with <samp></samp> HTML tag. In this tutorial, we will learn how to register a new format, add a button in the toolbar and apply the format when the button is clicked.

Register New Format

First, we need to register a new format using registerFormatType() function so that we can use it inside the formatting toolbar as a button. Create a new file e.g. custom-formats.js and en-queue it while registering the plugin scripts.

wp_enqueue_script(
        'custom-formats',
        plugins_url('custom-formats.js', __FILE__),
        array('wp-rich-text'),
        filemtime( plugin_dir_path( __FILE__ ) . 'custom-formats.js' ),
        true
);

Now add the following code inside the custom-formats.js file to register the custom format:

( function( wp ) {
    wp.richText.registerFormatType(
        'custom-formats/task-done', {
            title: 'Task Done',
            tagName: 'samp',
            className: 'task-done',
        }
    );
} )( window.wp );

The format is registered and now we need to add a button to the formatting toolbar which when clicked, will apply the format to the selected text. Following code inside custom-format.js file will register the button inside the toolbar using RichTextToolbarButton component.

( function( wp ) {
    var myButton = function( props ) {
        return wp.element.createElement(
            wp.editor.RichTextToolbarButton, {
                icon: 'yes-alt',
                title: 'Task Done',
                onClick: function() {
                    console.log( 'toggle format' );
                },
            }
        );
    }
    wp.richText.registerFormatType(
        'custom-formats/task-done', {
            title: 'Task Done',
            tagName: 'samp',
            className: 'task-done',
            edit: myButton,
        }
    );
} )( window.wp );

Note: Make sure to pass wp-element and wp-editor packages as dependencies while registering the custom-formats.js file.

If you want to show the format only for specific blocks then following code snippet can be used. The example snippet make sure that the format is only available for paragraph block.

( function( wp ) {
    var withSelect = wp.data.withSelect;
    var ifCondition = wp.compose.ifCondition;
    var compose = wp.compose.compose;
    var myButton = function( props ) {
        return wp.element.createElement(
            wp.editor.RichTextToolbarButton, {
                icon: 'yes-alt',
                title: 'Task Done',
                onClick: function() {
                    console.log( 'toggle format' );
                },
            }
        );
    }
    var ConditionalMyButton = compose(
        withSelect( function( select ) {
            return {
                selectedBlock: select( 'core/editor' ).getSelectedBlock()
            }
        } ),
        ifCondition( function( props ) {
            return (
                props.selectedBlock &&
                props.selectedBlock.name === 'core/paragraph'
            );
        } )
    )( myButton );
    wp.richText.registerFormatType(
        'custom-formats/task-done', {
            title: 'Task Done',
            tagName: 'samp',
            className: 'task-done',
            edit: ConditionalMyButton,
        }
    );
} )( window.wp );

Note: Please make sure to pass wp-compose and wp-data to dependencies array while registering the custom-formats.js file.

Apply Format When Button Is Clicked

Currently, when we click the Task Done button, it only prints ‘toggle format’ inside browser console. Now we will apply custom styles when the button is clicked. Following code will toggle the format when the button is clicked.

...
...
var myButton = function( props ) {
        return wp.element.createElement(
            wp.blockEditor.RichTextToolbarButton, {
                icon: 'yes-alt',
                title: 'Task Done',
                onClick: function() {
                    props.onChange( wp.richText.toggleFormat(
                        props.value,
                        { type: 'custom-formats/task-done' }
                    ) );
                },
                isActive: props.isActive,
            }
        );
 }
...
...