Skip to main content

Using components

Block and inline component syntax#

Components can be used in two ways: block-level or inline-level.

For example, given an icon_button component.

icon_button.html
<button>{{ children }} {% icon name=icon %}</button>

We can use the block syntax to pass the label of the button as children.

{% #icon_button icon="star" %}Favorite{% /icon_button %}

Note that # denotes the opening tag and / denotes the closing tag.

Output
<button>Favorite <svg>...</svg></button>

If we didn't need to pass a label, or if the component itself doesn't use {{ children }}, we can use the inline syntax instead.

{% icon_button icon="heart" %}

The inline syntax just uses the plain component name. No # or /.

Output
<button><svg>...</svg></button>

Component context#

Unlike the include tag, component template tags do not pass the current context to the child component. Variables need to be passed in explicitly.

{% #button variant="primary" size="large" %}Hello{% /button %}

In addition, any variable set inside of a component template does not leak out to to the global context.

{% var class=class|default:"btn btn-primary" %}<button {% attrs class %}>{{ children }}</button>
{# The `class` variable will not "leak" out onto the global context #}

This is a deliberate design decision to improve readability and reduce side-effects.

You can of course still use {% include %} if its behaviour is more convenient in specific circumstances.

Assigning output to a variable#

Similar to a fragment tag, a component's output can be assigned to a variable.

{% #heading variant="large" as my_heading %}Hello, World{% /heading %}
{# Render it like a normal variable #}{{ my_heading }}
{# Or pass to to another component #}{% card_heading heading=my_heading %}
note

Assigning component output to a variable cannot be done inside a with block.