Block attributes

November 22 2021

Hi friend!
This article contains material that is out of date and it is being rewritten. Thank you for your patience while I update the text content and code examples to work with the latest version of Gutenberg.

Level: Beginner, developer

Estimated reading time: 5 minutes


With the block editor, the terminology is sometimes fuzzy because it is a large project. When I talk about block attributes in this lesson, the scope is attributes that affects how a block works, or that can affect our design decisions.

This can be a block attribute, as defined in the documentation:

Attributes provide the structured data needs of a block. They can exist in different forms when they are serialized, but they are declared together under a common interface.

It can also refer to block supports, depending on the component:

Download the code example for render_block


In the previous lesson I mentioned attributes and their basic usage. Attributes are assigned to blocks on block creation.

File example: gutenberg\packages\block-library\src\categories\block.json

	"name": "core/categories",
	"category": "widgets",
	"attributes": {
		"align": {
			"type": "string",
			"enum": [ "left", "center", "right", "wide", "full" ]
		"className": {
			"type": "string"
		"displayAsDropdown": {
			"type": "boolean",
			"default": false
		"showHierarchy": {
			"type": "boolean",
			"default": false
		"showPostCounts": {
			"type": "boolean",
			"default": false

Each block has a limited set of attributes.

To recap:

A block attribute is added to the block comment as a serialized JSON object
with a key and a value.


This helps us identify and style block variations.

Full site editing has brought us a new attribute called tagName.

<!-- wp:group {"tagName": "section"} -->
<section class="wp-block-group">

You will be using this together with the group block. It allows us to replace the default div with a different element. For example a header, main, section or footer.

One of the most common attributes that you will use, is the additional CSS class.

The key is className, and the value, “sales-promo”.

<!-- wp:group {"className":"sales-promo","backgroundColor":"primary"} -->
<div id="sales" class="wp-block-group sales-promo has-primary-background-color 

The second block attribute that you can see in this image is the HTML anchor. It is added as an ID directly on our div.

[ Screen: refers to the code example above ]

If we wanted to make our example group wider, we would add the key: align, with the value: wide, and the class name: alignwide.

<!-- wp:group {"align":"wide","className":"sales-promo",
"backgroundColor":"primary"} -->

<div class="wp-block-group alignwide sales-promo
has-primary-background-color has-background" id="sales">

And for a full width block we would use the key: align with the value: full,
and the class name alignfull.

<!-- wp:group {"align":"wide"} -->

<div class="wp-block-group alignwide">

<!-- wp:group {"align":"full"} -->

<div class="wp-block-group alignfull">

All of our alignments follow the same pattern.

The columns block combines the default alignments on the outer block with a column width.
If you want to change the column width in your code, you need to edit both the value of the width attribute and the percentage for the flex-basis.

<!-- wp:columns -->
<div class="wp-block-columns"><!-- wp:column {"width":80} -->
<div class="wp-block-column" style="flex-basis:80%"></div>
<!-- /wp:column -->

<!-- wp:column {"width":20} -->
<div class="wp-block-column" style="flex-basis:20%">
<!-- /wp:column --></div>
<!-- /wp:columns -->

The color options work differently.

Like I hinted in the previous video, if you are using a predefined color
you will be using the backgroundColor and textColor attributes.

<!-- wp:group {"backgroundColor":"primary"} -->
<div class="wp-block-group has-primary-background-color has-background"><div class="wp-block-group__inner-container"></div></div>
<!-- /wp:group -->

When you are using a custom color, or a color selected from the color picker
you will be using the style attribute in combination with
color, background or text, and the color code.

<!-- wp:group {"style":{"color":{"background":"#1eadea"}}} -->
<div class="wp-block-group has-background" style="background-color:#1eadea"><div class="wp-block-group__inner-container"></div></div>
<!-- /wp:group -->

There are many attributes that are specific to one type of block.
When we add headings, the default heading level is an H2. To use a different heading level, we make use of a key called level, and the number of the level.

Note that the H2 heading has an empty block comment.

<!-- wp:heading {"level":1} -->
<h1>H1 heading</h1>
<!-- /wp:heading -->

<!-- wp:heading -->
<h2>H2 heading</h2>
<!-- /wp:heading -->

<!-- wp:heading {"level":3} -->
<h3>H3 heading</h3>
<!-- /wp:heading -->

<!-- wp:heading {"level":4} -->
<h4>H4 heading </h4>
<!-- /wp:heading -->

That concludes the summary of our most common blocks and attributes.

Adding new CSS classes depending on attributes

What about making changes to add or remove block attributes? If we loop back, I mentioned that attributes are added on block creation. Most of the time, you will find that making major changes is better suited for plugins.

But if you need to alter CSS classes for the presentational layer, you can use the render block filter.

apply_filters( 'render_block', string $block_content, array $block )

This filter is useful for many different scenarios. The filter has two parameters: $block_content, and $block.

(string) The block content about to be appended.

(array) The full block, including name and attributes.

By using the $block parameter, we can find the block name and the block attributes.

I am not going to show you the whole array, because with the inner blocks, it is rather large. What we are interested in, is only the first two parts.

Array ( [blockName] => core/column [attrs] => 
Array ( [width] => 80 ) 
[innerBlocks] => Array ( ) 
[innerHTML] => [innerContent] =>

I have created a new PHP function to use with the filter.

function prefix_filter_column_class( $block_content, $block ) {
if ( 'core/column' === $block['blockName'] ) {
	$block_attr = $block['attrs'];

	if ( isset( $block_attr['width'] ) && $block_attr['width'] > 50 ) {

	$block_content = str_replace( 'class="wp-block-column', 'class="wp-block-column wide-column ', $block_content );

	} elseif ( isset( $block_attr['width'] ) && $block_attr['width'] < 50 ) {

$block_content = str_replace( 'class="wp-block-column', 'class="wp-block-column narrow-column ', $block_content );

	return $block_content;

add_filter( 'render_block', 'prefix_filter_column_class', 10, 2 );

First, I want to make sure that I am filtering the correct block. Then I am checking if there is a width attribute and if the column is wide, or narrow.

Depending on the width, I am adding two new classes, wide-column or narrow-column.

And at the end, we need to return the block content that we altered.

So, that’s one way to do it on the server side with PHP. For those who are better at JavaScript than me :), I will include some links in the course material.