Using attributes in templates

Many Twig templates will have one or more Attribute objects passed in as variables. The purpose of the Attribute object is to store a set of HTML attributes, providing developers with helpful methods for interacting with this data and making it easy to print attributes. For example, attribute.addClass('myclass') makes it easy to add a class without worrying about precise string concatenation.

Typically, attributes in a template should look like this:

<div{{ attributes }}></div>

There should be no spaces between the tag name and the Twig syntax. The "stable" theme included in the Drupal 8 core has many examples of attributes to study.

By default, all templates have access to the following attribute object variables: attributes, title_attributes, and content_attributes.

You can use your debugger (kint(), dump(), dpm(), etc.) to check what's available. Below is an example using {{ kint(attribute) }} in the node.html.twig file.

Attribute Methods

attributes.addClass()

Adds a class or merges it into the array of existing CSS classes.

Single class:

<div{{ attributes.addClass('my-class') }}></div>

Multiple classes:

{%
  set classes = [
    'red',
    'green',
  ]
%}
<div{{ attributes.addClass(classes) }}></div>

Outputs: <div class="red green"></div>.

attributes.removeClass()

Removes a class from the Attribute object. Used similarly to addClass. Suppose you receive class variables from somewhere else, such as a preprocess function.

{% set classes = [ 'red', 'green', 'blue' ] %}

<div{{ attributes.addClass(classes).removeClass('green') }}></div>

Outputs: <div class="red blue"></div>.

attribute.setAttribute($attribute, $value)

Sets the value of an attribute key.

<div{{ attributes.setAttribute('id', 'myID') }}></div>

Outputs: <div id="myID"></div>

attributes.removeAttribute($attribute)

Removes an attribute from the Attribute object.

<div{{ attributes.removeAttribute('id') }}></div>

attributes.hasClass($class)

Checks if the class array contains a specific CSS class.

{% if attributes.hasClass('myClass') %}
  {# do stuff #}
{% endif %}

Create Attributes in Twig

As of Drupal 8.3.x, there is a new Twig function create_attribute(). See the change notice: https://www.drupal.org/node/2818293

This provides a new empty Attribute object for creating attributes.

{% set my_attribute = create_attribute() %}
{%
  set my_classes = [
    'kittens',
    'llamas',
    'puppies',
  ]
%}
<div{{ my_attribute.addClass(my_classes).setAttribute('id', 'myUniqueId') }}>
  {{ content }}
</div>

<div{{ create_attribute({'class': ['region', 'region--header']}) }}>
  {{ content }}
</div>

Other Useful Snippets

Dot notations can be chained:

{% set classes = ['red', 'green', 'blue'] %}
{% set my_id = 'specific-id' %}
{% set image_src = 'https://www.drupal.org/files/powered-blue-135x42.png' %}

<img{{ attributes.addClass(classes).removeClass('green').setAttribute('id', my_id).setAttribute('src', image_src) }}>

Outputs: <img id="specific-id" class="red blue" src="https://www.drupal.org/files/powered-blue-135x42.png">

Using the without filter

The Twig without filter removes part of the attributes:

<div class="myclass {{ attributes.class }}"{{ attributes|without('class') }}></div>

Note: In most cases, it’s better to use addClass() instead of the pattern above.

Be extremely cautious when assigning attributes manually in Twig templates. Always enclose attribute strings in double quotes, or your site may be vulnerable to XSS attacks. Twig automatically escapes content inside double quotes to protect against XSS.

This Twig template:

<b class={{ attributes.class }}>Hello<b>

With user input:

foo onclick=alert(bar)

Outputs:

<b class=foo onclick=alert(bar)>Hello</b>

This Twig template with double quotes:

<b class="{{ attributes.class }}">Hello<b>

Will output from the same input:

<b class="foo " onclick="alert(bar)">Hello</b>

Modifying the attribute without

{% set attributes = attributes.addClass('my-class') %}
<div{{ attributes }}></div>