5

Directives: control your component's behavior

Directives are special attributes that direct an element’s behavior. Use them to create conditionals, set an attribute, skip evaluation, and more.

Use directives in HTML, standard components, custom component templates and our optional, top-level elements of your email to set attributes dynamically and conditionally add/remove them. Every directive begins with #.

For instance, you can use #if, #else-if, and #else for conditionally displaying these tags:

<script>
    const useExternal = true;
</script>
<link #if="useExternal" rel="stylesheet" href="https://example.com/hosted.css">
<style #else>
    /* local CSS */
</style>

You can also dynamically set properties on the <title> , <meta> and <link> tags using #set.

List of directives

#if

Conditionally render an element based on whether the given JavaScript expression is truthy.

Accepts: any

<div #if="lang === 'en'">Hello</div>

#else-if

Chain this to a sibling element with an #if or #else-if directive. If none of the leading conditions are true, this element will render. It must be the last item in a conditional chain.

Accepts: any

<div #if="lang === 'en'">Hello</div>
<div #else-if="lang === 'es'">Hola</div>

#else

Chain this to a sibling element with an #if or #else-if directive. If none of the leading conditions are true, this element will render. It must be the last item in a conditional chain.

Accepts: nothing

<div #if="lang === 'en'">Hello</div>
<div #else-if="lang === 'es'">Hola</div>
<div #else>Bonjour</div>

#each

This allows you to iterate over lists of values and render the element for each value.

Accepts: Array | Object | number | string

<div #each="item in items">${item}</div>

<div #each="(item, index) in items">${index} – ${item}</div>

<div #each="(value, key) in object">${key}: ${value}</div>

<div #each="(value, key, index) in object">${index} – ${key}: ${value}</div>

#set

This allows you to dynamically set an HTML attribute. The final value of the expression will be converted to a string and set as an attribute on the HTML element.

Set objects

You can pass an object to the #set directive to set multiple attributes at once.

<!-- source --> 
<div #set="{ id: 'my-id', class: 'my-class' }"></div>

<!-- result --> 
<div id="my-id" class="my-class"></div>

Set individual attributes

You can set individual attributes by setting the key after a colon (:) and the value.

<!-- source -->
<div #set:id="2*3*4"></div>

<!-- result -->
<div id="24"></div>

Shorthand

As a shorthand, you can simply add a : before an attribute.

<!-- these are equivalent -->

<div #set:id="2*3*4"></div>
<div :id="2*3*4"></div>

Set props on child components

You can pass all properties set on a component into a child component using #set="props".

<template>
  <x-paragraph #set="props"><slot/></x-paragraph>
</template>

#set:html

Dynamic values output as escaped by default to prevent accidentally injecting HTML. To skip escaping, use the #set:html directive.

<div #set:html="rawHTMLVariable"></div>

Use this with <fragment> to avoid adding an extra element to your output.

<fragment #set:html="rawHTMLVariable" />

#set:class

Setting a class can take either a string or an object.

Object

<div #set:class="['class1','class2','class3']" ></div>

String

<div #set:class="class1 class2 class3 " ></div>

In both cases, this is the output:

<div class="class1 class2 class3" ></div>

#set:style

Setting a style can take either a string or an object.

If you add a string, you must wrap the styles in backticks.

<div :style="`font-size:1em;color:green;font-family:${props[font-family]}`">

If you add an object, set the object in the <script> tag to keep your code cleaner and more readable.

const styleObject = {
    color: props['color'],
    'font-family': props['font-family'],
    'font-size': props['font-size'],
    'font-weight': props['font-weight'],
    'text-decoration': props['text-decoration'],
    'line-height': props['line-height'],
    'text-transform': props['text-transform'],
    'text-align': props['text-align'],
  };

Then when you set the style, the output code will be cleaner, absent of blank values and extra spacing.

<div :style="styleObject">

#class:*

This directive allows you to easily control whether a class is added. Use #set:class:* to dynamically set it.

Accepts: string

<div #class:my-class>Test</div>
<div #set:class:my-class="Math.random() > 0.5">Test</div>

#style:*

This directive allows you to set a style property and value. Use #set:style:* to dynamically set it.

Accepts: string

<div #style:background="blue">Test</div>
<div #set:style:background="Math.random() > 0.5 ? 'blue' : 'red'">Test</div>

#is

This directive allows you to set HTML elements as well as components. Use #set:is to dynamically set it.

Accepts: string | Component

Component

<a #is="custom-button">Click me</a>

<a #set:is="CustomButton">Click me</a>
<a #set:is="Math.random() > 0.5 ? CustomButton : AnotherButton">Click me</a>

HTML

<ul :is="orderedList ? 'ol' : 'ul'">
  <li></li>
</ul>

#is:raw

This directive indicates that any children of the element should be skipped for compilation. This is helpful when you are inserting text or attributes with conflicting syntax and you don’t want us to process it.

Accepts: Nothing

<div #is:raw>
<a #if="I am not evaluated">${I am also not evaluated}</a>
</div>

#slot

This directive tells us which slot to insert the element.

See Slots for more info.

Accepts: string

#slot cannot have dynamic values.

<layout>
  <fragment #slot="header">This goes in the header slot</fragment>
  <fragment>This goes in the default slot</fragment>
  <fragment #slot="footer">This goes in the footer slot</fragment>
</layout>