Components

Components help you organize blocks of markup that you use often by extracting them to a file, so you can reuse them in multiple templates.

We're testing a new components system for v4.4.0 - give it a try !

Usage

To create a Component, simply create an HTML file with a <content> tag:

src/components/example.html

<content></content>

The <content> tag will be replaced with the content passed to the Component.

You can safely omit the <content> tag if you want to use Components as includes, and don't actually need to pass any content to them.

You may use the <component> tag to insert a Component in a Template:

src/templates/example.html

<component src="src/components/example.html">
  This text will replace the `<content>` tag in the Component.
</component>

Example

Let's create a basic alert Component.

src/components/alert.html

<table class="w-full">
  <tr>
    <td class="px-4 py-2">
      <content></content>
    </td>
  </tr>
</table>

We could use it like this:

src/templates/example.html

<component
  src="src/components/alert.html"
  class="bg-red-100 text-red-700 rounded"
  role="alert"
>
  This is an alert!
</component>

Result:

src/templates/example.html

<table class="w-full bg-red-100 text-red-700 rounded" role="alert">
  <tr>
    <td class="px-4 py-2">
      This is an alert!
    </td>
  </tr>
</table>

As you can see, the Component's attributes are passed to the root tag (in our case the <table> tag), and the <content> tag is replaced with our content.

Variables

When creating a Component, you have access to global variables:

src/components/example.html

<div>
  Building for: {{ page.env }}
</div>

You can also manually provide data to the Component through attributes:

src/templates/example.html

<component
  src="src/components/example.html"
  env="{{ page.env }}"
  role="user"
>
  Building for: {{ env }}
  Role is: {{ role }}
</component>

Undefined variables

Sometimes you may need to use a Component without passing it the variables it uses. However, if you try to use an undefined variable in a Component, the build will fail.

For example, if you have this Component:

src/components/example.html

<div>
  Category: {{ category }}
</div>

... and try to use it like this:

src/templates/example.html

<component
  src="src/components/example.html"
></component>

... the build will fail.

To work around it, you can do a type check when using the variable:

src/components/example.html

<div>
  Category: {{ typeof category !== 'undefined' ? category : 'Uncategorized' }}
</div>

If you're using an <if> tag, you may check the type like this:

src/components/example.html

<if condition="typeof category !== 'undefined'">
  <div>
    Category: {{ category }}
  </div>
</if>

Ignoring expressions

Ignoring expressions inside a Component works as you'd expect:

src/components/example.html

Hello @{{ name | fallback: 'friend' }}!

<content></content>

Of course, you can ignore expressions when passing data or content to the Component:

src/templates/example.html

<component
  src="src/components/example.html"
  role="@{{ user.role }}"
>
  Hello @@{{ name | fallback: 'friend' }}!
</component>

Due to the way content passed to a Component is rendered, ignoring expressions needs to be done with @@{{ }} instead of @{{ }}.

This will be fixed with the new Components system in v4.4.0.

Ignoring raw blocks

Ignoring expressions inside <raw> blocks that you pass inside a Component currently doesn't work, you'd still need to use the @{{ }} syntax.

This will be fixed with the new Components system in v4.4.0.