pre_render_block │ filter-hook │ WP 5.1.0

Allows replacing a block's HTML before it is rendered or completely disabling its output.

The filter is called in render_block() and when nested blocks are processed in WP_Block::render(). It is suitable for static and dynamic blocks.

Usage

add_filter( 'pre_render_block', 'wp_kama_pre_render_block_filter', 10, 3 );

/**
 * Function for `pre_render_block` filter-hook.
 * 
 * @param string|null   $pre_render   The pre-rendered content.
 * @param array         $parsed_block An associative array of the block being rendered. See
 *                                    WP_Block_Parser_Block.
 * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block.
 *
 * @return string|null
 */
function wp_kama_pre_render_block_filter( $pre_render, $parsed_block, $parent_block ){
	// filter...
	return $pre_render;
}

$pre_render(string|null)

HTML to use instead of the rendering result.

• null — continue normal rendering.
• A string — replace the result with the specified HTML.
• An empty string '' — remove the block from the output.

Default: null.

If the block does not need to be changed, return the received $pre_render to preserve the result of previous callbacks.

WordPress checks the value strictly for null: any other value stops rendering. To disable output, use '', not false.

$parsed_block(array)

Data for the block being processed after parsing its markup.

• blockName(string|null)
  Block name, for example, core/paragraph. It can be null for freeform HTML outside blocks.

• attrs(array)
  Attributes from the block's HTML comment. This is not the complete set of attributes: values extracted from HTML can be absent here.

• innerBlocks(array of arrays)
  Nested blocks. Each item has the same structure as $parsed_block.

• innerHTML(string)
  HTML inside the block without the HTML of nested blocks.

• innerContent(array)
  HTML fragments and null values marking where nested blocks are inserted.

$parent_block(WP_Block|null)

Parent block object when processing a nested block in WP_Block::render().

When the filter is called from render_block(), null is always passed.

Examples

#1 Disable the Latest Posts block output

The core/latest-posts block will not be rendered, so its callback will not run a posts query.

add_filter( 'pre_render_block', 'my_disable_latest_posts_block', 10, 2 );

function my_disable_latest_posts_block( $pre_render, $parsed_block ) {

	if ( null !== $pre_render ) {
		return $pre_render;
	}

	if ( 'core/latest-posts' === $parsed_block['blockName'] ) {
		return '';
	}

	return $pre_render;
}

#2 Replace a block with custom HTML

In the Paragraph block settings, add the current-year CSS class. On output, replace such a block with a paragraph containing the current year.

add_filter( 'pre_render_block', 'my_render_current_year', 10, 2 );

function my_render_current_year( $pre_render, $parsed_block ) {

	if ( null !== $pre_render || 'core/paragraph' !== $parsed_block['blockName'] ) {
		return $pre_render;
	}

	$classes = preg_split( '/\s+/', $parsed_block['attrs']['className'] ?? '' );

	if ( ! in_array( 'current-year', $classes, true ) ) {
		return $pre_render;
	}

	return '<p class="current-year">' . esc_html( wp_date( 'Y' ) ) . '</p>';
}

The original paragraph HTML and its styling are completely replaced by the specified markup.