Home/ Documentation/ WordPress/ Actions/ Block Attributes

Block Attributes

Block Attributes action defines and uses one or more editable block attributes on the selected HTML element.

Block attributes are editable parts of the block, for example the title of its main heading, background image and so on.

Block Attributes action does two things:

  • Creates the control for the attribute in the block editor sidebar. For example, an input box, image selector and so on. This happens only the first time the attribute is used in the block. The settings that are used to define the control, such as Title and Control type, should be set on the first occurrence of the attribute.
  • Uses the attribute value on the selected element. For example, it sets the inner content of the element to the attribute value.

In most cases an attribute will be used only once within a block and these two operations will thus be combined. But it is possible to use the same attribute on multiple places within the block.

Attribute id 

Each attribute needs an id, such as title. Ids can contain only letters, numbers and the _ character.

Attribute ids don’t have to be unique within the whole project, only within the block. That means that two block types can both have an attribute with the id title.

Use as

How will we use the attribute on the selected element?

Choices are:

Content

Display the attribute value as the inner content of the element.

<h1>{ the attribute value }</h1>

Default control is text input box and editable text for regular JavaScript blocks. 

When placed on a <svg> element the attribute value will replace the whole SVG image.

Image

Use the attribute value as the src attribute of the <img> element. This option works on <img> and <svg> elements.

<img src=“{the attribute value}” />

Default control is the image selector.

Learn more about using inline SVGs.

Background image

Set the attribute value as the background-image property in the style attribute.

<div style=“background-image:url(‘{the attribute value}’);”>…</div>

Default control is the image selector.

Link

Set the attribute value to href attribute of the anchor element. This option requires an anchor element.

<a href=“{the attribute value}”>…</a>

Default control is the URL selector.

Style

Set the attribute value as the value of the inline style property.

<p style=“color:{the attribute value};”>…</p>

Default control is the color picker for color properties and text input for others. 

Note, for background image set Use as to Background image.

Using !important with attributes that are used to customize the inline style of the element is not supported on regular JavaScript blocks. The reason is that !important flag is not supported by React, the library upon which blocks are implemented in WordPress.

A workaround is to define a CSS class rule with high specificity or using the !important flag on the property, and then make the class editable with the attribute.

Another workaround is to use a dynamic PHP block.

Attribute

Set the value to a HTML element attribute.

<h1 title=“{the attribute value}”>…</h1>

Default control is text input.

Enter the attribute name in the Element attribute field. 

See the Replace or append setting to see how to append the value to the current attribute value.

Class

Append the attribute value to the class attribute.

<div class=“some-class {the attribute value}”>…</div>

Use Replace classes field to remove any existing classes before appending the attribute value. For example if the element has a default text-red class, we need to remove it before appending a dynamic value such as text-blue.

Default control is text input.

None

Do not use the value on anywhere on the element. Useful for combining with If empty setting to show the element only if the attribute is set.

Default control is text input.

Title

Title is a human friendly attribute name that is displayed in the sidebar. It is a part of the control definition.

Open Attribute options section for more settings.

If empty

What to do if the attribute value is not set? We have two options:

  • Use the default value
  • Remove the element from the output

Default value of an attribute is gathered in dependance on how it is used. For Content, the inner content of the HTML element is used as the default value. For Attribute, default value is the attribute value. And so on.

Control type

Control type setting lets us choose the type of control used in the block editor sidebar.

Auto

Automatically select the best control, based on how the attribute is used and what kind of information it contains.

Input

Display a simple text input box. For regular JavaScript blocks, the text will be also editable inline (on the block view), without formatting options.

Textarea

Display a multiline texture. For regular JavaScript blocks, the text will be also editable inline, without formatting options.

Rich text

Show a rich text multiline control in the sidebar. For regular JavaScript blocks, the text will be also editable inline, with formatting options.

Note, the formatting toolbar is always showed above the block, even when editing happens in the sidebar.

Select

Show a dropdown select. Use the Values field to specify options. Supported formats are:

value1
value2
...

or

Label1=value1
Label2=value2
...

Toggle

Display a toggle control. Use the Value field to set the active attribute value.

Link

Display a custom control for selecting or entering a URL. The control allows searching for posts (with post type selector) or entering a URL directly.

Image

Use an image selector control that allows uploading or selecting an image from the Media panel. Choosing the image size is also supported.

Color

Display a color picker control.

Expression

Expression lets us transform the value before it is applied to the element.

For example:

Welcome to {{ place }}, {{ name }}!

In the above example, place and name are both attribute ids defined on the block.

Only attribute ids can be used inside the {{ ... }} brackets. Function calls or other expressions are not supported.

Help

Add additional information that will help the user understand what the attribute does.

Add  attribute

Click on the Add attribute button to use additional attributes on the element.

Using the same element in multiple places

We can use the same attributes in different roles, on different elements within the same block.

For example, we can declare the id attribute on the top block element and set its value to the id attribute of the element.

And then we can use the same id attribute to set the href attribute of a navigation control within the same block. In this example we want the href to contain #<id>. We set the href to # in the source and then use Append to the current value setting.

Important thing to keep in mind is to set the Title, Control type, Help and other control properties only on the first instance of the attribute. Any repeated settings of these properties are ignored.

Using the attribute only as the condition for displaying the element

Block Attributes action can define multiple attributes.

In some cases, we just want to display the element if an attribute is set, without using the attribute value on the element.

For example, our block might need an attribute active that is controlled with a toggle control. Inside the block we have a div that should only be displayed if the active is set, without the value of active being displayed in its content or attribute.

To do that, we add Block Attributes action to the DIV, set the id to active and then set Use as to None and set If not set to Remove the element. Set the control type to Toggle and value too true, or similar.

The DIV will be only displayed if active is set.



Last updated on November 10, 2021 at 2:36 am


Print this article