render_block_(name) │ filter-hook │ WP 5.7.0

Allows changing the HTML of the specified block after it is rendered.

Replace (name) with the full block name including its namespace:

• render_block_core/paragraph — paragraph.
• render_block_core/image — image.
• render_block_core/group — group.
• render_block_my-plugin/example — custom block.

The filter is called in WP_Block::render() after the general render_block filter. It works for static and dynamic blocks, including nested ones. It changes the output but not the saved post content.

Usage

add_filter( 'render_block_(name)', 'wp_kama_render_block_name_filter', 10, 3 );

/**
 * Function for `render_block_(name)` filter-hook.
 * 
 * @param string   $block_content The block content.
 * @param array    $block         The full block, including name and attributes.
 * @param WP_Block $instance      The block instance.
 *
 * @return string
 */
function wp_kama_render_block_name_filter( $block_content, $block, $instance ){
	// filter...
	return $block_content;
}

$block_content(string)

Block HTML after rendering and processing by previous filters.

Return the modified HTML or the original value. An empty string '' removes the block from the output, but rendering itself has already been performed at this point.

$block(array)

Block data.

• blockName(string)
  Full block name, for example, core/image.

• attrs(array)
  Block attributes from its HTML comment. Attributes extracted from HTML can be absent.

• innerBlocks(array of arrays)
  Nested blocks with the same data structure.

• innerHTML(string)
  Original block HTML without the HTML of nested blocks. It is not equivalent to the finished $block_content.

• innerContent(array)
  HTML fragments and null values at the positions of nested blocks.

$instance(WP_Block)

Current WP_Block{} object.

Examples

#1 Add a CSS class to all Paragraph blocks

Use WP_HTML_Tag_Processor{} to add a class to the <p> tag while preserving the other attributes.

add_filter( 'render_block_core/paragraph', 'my_add_paragraph_class' );

function my_add_paragraph_class( $block_content ) {

	$processor = new WP_HTML_Tag_Processor( $block_content );

	if ( $processor->next_tag( 'P' ) ) {
		$processor->add_class( 'custom-paragraph' );
	}

	return $processor->get_updated_html();
}

#2 Add a wrapper to images of a specific size

Check the sizeSlug attribute and wrap images with the large size in an additional container.

add_filter( 'render_block_core/image', 'my_wrap_large_image', 20, 2 );

function my_wrap_large_image( $block_content, $block ) {

	if ( '' === trim( $block_content ) ) {
		return $block_content;
	}

	if ( 'large' !== ( $block['attrs']['sizeSlug'] ?? '' ) ) {
		return $block_content;
	}

	return '<div class="large-image-wrapper">' . $block_content . '</div>';
}

There is no need to check $block['blockName'] here: the callback is called only for core/image.