Home » Documentation » How to connect your blockStyle components

How to connect your blockStyle components

This section demonstrates how to implement an opacity style for blocks using both editor-side JavaScript and server-side PHP. Both need to be set.

Table of Contents

JavaScript implementation

Step 1: Register Renderer

Retrieve WordPress editor hooks and the data store to register your renderer like below. Be sure it runs on domReady to wait for the datastore.

/**
 * Local WP references.
 *
 * - `addFilter`: Allows modifying block settings or editor behavior.
 * - `dispatch`: Provides access to data stores, e.g., registering renderers.
 * - `domReady`: Runs code once the editor DOM is fully initialized.
 */
const {
    hooks: { addFilter },
    data: { dispatch },
    domReady,
} = wp;


/**
 * Register the opacity renderer when the editor is ready.
 *
 * - `opacity` is the style key in block style attribute.
 * - `renderStyles` generates the CSS for the block based on its attributes.
 * - `10` is the priority of the renderer (usage like add_filter in wordpress).
 */
domReady( () => {
    dispatch( 'quantumpress/viewports' )?.registerRenderer(
        'opacity',
        renderStyles,
        10
    );
} );

Step 2: Utility Function for CSS Generation

stylesToCss converts key-value style objects into valid CSS strings, isolating the CSS string generation from the main renderer logic.

/**
 * Converts an object of CSS properties into a valid CSS string.
 *
 * Example:
 *   { opacity: 0.5, color: 'red' } => "opacity:0.5;color:red;"
 *
 * @param styles - An object with CSS property value pairs
 *
 * @returns A string containing the concatenated CSS rules.
 */
function stylesToCss( styles ) {
    let css = '';

    for ( const property in styles ) {
        if ( Object.prototype.hasOwnProperty.call( styles, property ) ) {
            css += property + ':' + styles[ property ] + ';';
        }
    }

    return css;
}

Step 3: Render CSS Styles from block attributes

The renderStyles function reads the opacity attribute, converts it from percentage to decimal, and outputs a CSS rule string for the editor preview.

/**
 * Render CSS for opacity style.
 *
 * This function converts the stored opacity value (0–100) into a decimal (0–1)
 * and returns a CSS rule string for the given selector.
 *
 * @param styles - The style attributes object for the block.
 * @param options.selector - The CSS selector for the block.
 *
 * @returns A string containing the CSS rule
 */
function renderStyles(
    styles,
    { selector }
): string {
    const { value } = styles.opacity || {};

    if ( value === undefined ) {
        return '';
    }

    const compiled = {
        opacity: +(value / 100).toFixed( 2 ),
    };

    return selector + '{' + stylesToCss( compiled ) + '}';
}

PHP Implementation

Step 1: Define the Opacity Renderer

On the server side, we create a single class to handle opacity styles.
This class converts a stored percentage (0–100) into a CSS decimal (0.0–1.0) and outputs a CSS rule string.

The constructor attaches the render method to a dynamic WordPress filter hook called:

quantum_viewports_register_renderer_${styleKey}

Step 2: Helper Method for CSS Generation

The small helper method stylesToCss converts an associative array of CSS properties into a valid CSS string. This mirrors the JavaScript stylesToCss function and ensures consistent output between editor and frontend.

Step 3: Render the Opacity CSS

The render method:

  1. Reads the stored opacity value from the block.
  2. Converts it from 0–100 to 0.0–1.0.
  3. Returns a CSS rule using the % placeholder for the block selector.
<?php

defined( 'ABSPATH' ) || exit;

/**
 * Class OpacityRenderer
 *
 * Handles rendering of opacity styles for blocks.
 * Converts a stored percentage value into a valid CSS opacity rule
 *
 * Registration:
 *  - The renderer is hooked into 'quantum_viewports_register_renderer_opacity'
 *    to be called when viewport styles are generated.
 */
class OpacityRenderer
{
    /**
     * The style property key this renderer is responsible for.
     *
     * @var string
     */
    protected string $property = 'opacity';

    /**
     * Constructor.
     *
     * Registers the render callback with WordPress using add_filter.
     */
    public function __construct()
    {
        add_filter(
            'quantum_viewports_register_renderer_' . $this->property,
            [ $this, 'render' ],
            10,
            3
        );
    }


    /**
     * Convert an associative array of CSS properties into a CSS string.
     *
     * Example:
     * [ 'opacity' => 0.5, 'color' => 'red' ] => "opacity:0.5;color:red;"
     *
     * @param array $styles Associative array of CSS properties.
     *
     * @return string The concatenated CSS string.
     */
    protected function stylesToCss( array $styles ): string
    {
        $css = '';
        foreach ( $styles as $key => $value ) {
            $css .= $key . ':' . $value . ';';
        }
        return $css;
    }


    /**
     * Render the CSS for the opacity property.
     *
     * Converts a percentage-based opacity value into a decimal and generates
     * a CSS rule string using the provided selector placeholder '%'.
     *
     * @param string $css    Existing CSS string.
     * @param array  $styles Array containing style values, expected key 'value'.
     * @param array  $valids Optional array of validated style keys.
     *
     * @return string A CSS rule string, or an empty string if no value is set.
     */
    public function render( string $css, array $styles, array $valids ): string
    {
        $value = $styles['value'] ?? null;

        if ( $value === null ) {
            return '';
        }

        $compiled = [
            'opacity' => number_format( $value / 100, 2, '.', '' ),
        ];

        return '%' . '{' . $this->stylesToCss( $compiled ) . '}';
    }
}

How it all works together

  • The JavaScript renderer handles the editor preview. It reads block attributes, converts values, and outputs CSS in real time.
  • The PHP renderer generates the final CSS for the front-end. It ensures that the styles applied in the editor are consistent when rendered on the website.
  • Both renderers share the same style key (opacity) and CSS generation logic (stylesToCss), ensuring predictable results across editor and frontend.