Craft 3 Documentation

Twig Primer

Here’s a rundown of the core concepts in Twig, the templating engine used by Craft.

This is only meant as a primer, not a comprehensive documentation of everything Twig can do.

To learn more, visit the Continued Reading section at the bottom of this page or refer directly to the official Twig documentation .

Three Types of Twig Tags #

There are three types of tags in Twig:

Let’s review each one in more detail.

Logic Tags #

Logic tags control what happens in your template. They can set variables, test conditionals, loop through arrays, and much more.

Logic tags don’t output anything to the template on their own.

Their syntax always begins with “{%” and ends with “%}”. What happens in between is up to the tag you’re using.

<p>Is it quitting time?</p>

{% set hour = now|date("G") %}
{% if hour >= 16 and hour < 18 %}
    <p>Yes!</p>
{% else %}
    <p>Nope.</p>
{% endif %}

Output Tags #

Output tags are responsible for printing things out to the rendered HTML.

Their syntax always begins with “{{” and ends with “}}”. You can put just about anything inside them – as long as Twig can evaluate it into a string.

<p>The current time is {{ now|date("g:i a") }}.</p>

Output tags are only for outputting to the template, so you never place output tags within statement tags in Twig.

These examples are incorrect:

{% set entry = craft.entries.section( {{ sectionId }} ).first() %}
{% set entry = craft.entries.section( {% if filterBySection %} sectionId {% endif %} ) %}

These are correct:

{% set entry = craft.entries.section( sectionId ).first() %}
{% set entry = craft.entries.section( filterBySection ? sectionId : null ) %}

Resources:

Comment Tags #

You can leave comments for future self in the code using comment tags. Twig won’t evaluate anything inside the comment tags; it will simply pretend they don’t exist.

The comment syntax always begins with “{#” and ends with “#}”.

{# Loop through the recipes #}

Anything put inside of the comments tags will not render to the final template, not even as an HTML comment.

Variables #

Variables in Twig are just like variables in Javascript or any other programming language. There are different types of variables – strings, arrays, booleans, and objects. You can pass them into functions, manipulate them, and output them.

You can assign your own variables using the set tag:

{% set style = 'stirred' %}

{{ style }}

Additionally, all of your Craft templates are pre-loaded with a few global variables:

Filters #

You can manipulate variables with filters. The syntax is the variable name followed by a pipe (|) followed by the filter name:

{{ siteName|upper }}

Some filters accept parameters::

{{ now|date("M d, Y") }}

Resources:

Functions #

Twig and Craft provide several functions that you can use within your template tags:

<h3>Watch me count to ten!</h3>
<ul>
    {% for num in range(1, 10) %}
        <li class="{{ cycle(['odd', 'even'], loop.index0) }}">
            {{ num }}
        </li>
    {% endfor %}
</ul>

Resources:

Continued Reading #

There are several learning resources available online for learning Twig: