get_block_wrapper_attributes() │ WP 5.6.0

Generates a string of HTML attributes for the wrapper of the current block, adding to them all styles and capabilities declared via block supports.

The function takes the attributes that WordPress has formed for the block (alignment classes, colors, spacing, custom data, etc.) — and merges them with the values you passed and returns a ready-to-use string of block tag attributes.

The resulting string is already sanitized, so it can be safely inserted directly into the opening HTML tag of the block wrapper.

The method already escapes each value, so do not wrap the result in esc_attr().

Call context

The function should be called only in the place where the block's HTML is actually generated — inside the block render function or in a PHP template that WordPress processes as a block template.

In other words, during the rendering of a specific block instance, when the engine has already:

  1. Parsed the block JSON metadata and learned which “block supports” are available to it.
  2. Merged the attributes set by the editor (colors, alignment, custom classes, etc.).
  3. Passed this data to your PHP code.

If you call it somewhere outside of this context — for example, in a regular hook callback that is not related to the current block — the attributes array will not yet be formed, and the function will return an empty string.

The function works based on WP_Block_Supports::apply_block_supports(), which depends on the correctly filled variable WP_Block_Supports::$block_to_render, which in turn is set before calling the render_callback function in the WP_Block::render() method:

WP_Block_Supports::$block_to_render = $this->parsed_block;

$block_content = (string) call_user_func( $this->block_type->render_callback, $this->attributes, $block_content, $this );
Uses: WP_Block_Supports::apply_block_supports()

No Hooks.

Returns

String.

  • String — ready-to-insert attributes.
  • Empty string — if there are no final attributes (neither from core nor from you).

Usage

get_block_wrapper_attributes( $extra_attributes );
$extra_attributes(array)

Additional attributes for the block wrapper as an array of strings. For example:

[
	'class'      => 'card card--highlight',
	'style'      => 'background:#f5f5f5',
	'data-id'    => 42,
	'aria-label' => __( 'Card', 'textdomain' ),
]

By default only style, class, id and aria-label are merged. Any other keys are added “as is”.

Default: []

Examples

1

#1 Basic output of a dynamic block

Add wrapper attributes in the block render function.

function myplugin_render_dynamic_block( $attributes, $content ) {
	$wrapper_attributes = get_block_wrapper_attributes();

	return sprintf(
		'<div %1$s>%2$s</div>',
		$wrapper_attributes,
		$content
	);
}
0

#2 Additional custom attributes

Passing a custom class, inline style and a data attribute.

$wrapper_attributes = get_block_wrapper_attributes( [
	'class'      => 'card card--highlight',
	'style'      => 'background: #f5f5f5',
	'data-id'    => 42,
	'aria-label' => 'Card',
] );

echo sprintf( '<section %s>…</section>', $wrapper_attributes );

Changelog

Since 5.6.0 Introduced.

get_block_wrapper_attributes() code WP 6.9.1

wp-includes/class-wp-block-supports.php 
function get_block_wrapper_attributes( $extra_attributes = array() ) {
	$new_attributes = WP_Block_Supports::get_instance()->apply_block_supports();

	if ( empty( $new_attributes ) && empty( $extra_attributes ) ) {
		return '';
	}

	// This is hardcoded on purpose.
	// We only support a fixed list of attributes.
	$attributes_to_merge = array( 'style', 'class', 'id', 'aria-label' );
	$attributes          = array();
	foreach ( $attributes_to_merge as $attribute_name ) {
		if ( empty( $new_attributes[ $attribute_name ] ) && empty( $extra_attributes[ $attribute_name ] ) ) {
			continue;
		}

		if ( empty( $new_attributes[ $attribute_name ] ) ) {
			$attributes[ $attribute_name ] = $extra_attributes[ $attribute_name ];
			continue;
		}

		if ( empty( $extra_attributes[ $attribute_name ] ) ) {
			$attributes[ $attribute_name ] = $new_attributes[ $attribute_name ];
			continue;
		}

		$attributes[ $attribute_name ] = $extra_attributes[ $attribute_name ] . ' ' . $new_attributes[ $attribute_name ];
	}

	foreach ( $extra_attributes as $attribute_name => $value ) {
		if ( ! in_array( $attribute_name, $attributes_to_merge, true ) ) {
			$attributes[ $attribute_name ] = $value;
		}
	}

	if ( empty( $attributes ) ) {
		return '';
	}

	$normalized_attributes = array();
	foreach ( $attributes as $key => $value ) {
		$normalized_attributes[] = $key . '="' . esc_attr( $value ) . '"';
	}

	return implode( ' ', $normalized_attributes );
}

Gutenberg (blocks editor)

Block Editor (Gutenberg)