Template Directives Reference

Template directives are a special kind of HTML attribute available inside of any Astro component template (.astro files), and some can also be used in .mdx files.

Template directives are used to control an element or component’s behavior in some way. A template directive could enable some compiler feature that makes your life easier (like using class:list instead of class). Or, a directive could tell the Astro compiler to do something special with that component (like hydrating with client:load).

This page describes all of the template directives available to you in Astro, and how they work.

Rules

Section titled Rules

For a template directive to be valid, it must:

• Include a colon : in its name, using the form X:Y (ex: client:load).
• Be visible to the compiler (ex: <X {...attr}> would not work if attr contained a directive).

Some template directives, but not all, can take a custom value:

• <X client:load /> (takes no value)
• <X class:list={['some-css-class']} /> (takes an array)

A template directive is never included directly in the final HTML output of a component.

Common Directives

Section titled Common Directives

class:list

Section titled class:list

class:list={...} takes an array of class values and converts them into a class string. This is powered by @lukeed’s popular clsx helper library.

class:list takes an array of several different possible value kinds:

• string: Added to the element class
• Object: All truthy keys are added to the element class
• Array: flattened
• false, null, or undefined: skipped

<!-- This -->
<span class:list={[ 'hello goodbye', { world: true }, [ 'friend' ] ]} />
<!-- Becomes -->
<span class="hello goodbye world friend"></span>

set:html

Section titled set:html

set:html={string} injects an HTML string into an element, similar to setting el.innerHTML.

The value is not automatically escaped by Astro! Be sure that you trust the value, or that you have escaped it manually before passing it to the template. Forgetting to do this will open you up to Cross Site Scripting (XSS) attacks.

---
const rawHTMLString = "Hello <strong>World</strong>"
---
<h1>{rawHTMLString}</h1>
  <!-- Output: <h1>Hello &lt;strong&gt;World&lt;/strong&gt;</h1> -->
<h1 set:html={rawHTMLString} />
  <!-- Output: <h1>Hello <strong>World</strong></h1> -->

You can also use set:html on a <Fragment> to avoid adding an unnecessary wrapper element. This can be especially useful when fetching HTML from a CMS.

---
const cmsContent = await fetchHTMLFromMyCMS();
---
<Fragment set:html={cmsContent}>

set:html={Promise<string>} injects an HTML string into an element that is wrapped in a Promise.

This can be used to inject HTML stored externally, such as in a database.

---
import api from '../db/api.js';
---
<article set:html={api.getArticle(Astro.props.id)}></article>

set:html={Promise<Response>} injects a Response into an element.

This is most helpful when using fetch(). For example, fetching old posts from a previous static-site generator.

<article set:html={fetch('http://example/old-posts/making-soup.html')}></article>

set:html can be used on any tag and does not have to include HTML. For example, use with JSON.stringify() on a <script> tag to add a JSON-LD schema to your page.

<script type="application/ld+json" set:html={JSON.stringify({
  "@context": "https://schema.org/",
  "@type": "Person",
  name: "Houston",
  hasOccupation: {
    "@type": "Occupation",
    name: "Astronaut"
  }
})}/>

See how client-side scripts work in Astro components.

define:vars

Section titled define:vars

define:vars={...} can pass server-side variables from your component frontmatter into the client <script> or <style> tags. Any JSON-serializable frontmatter variable is supported, including props passed to your component through Astro.props. Values are serialized with JSON.stringify().

---
const foregroundColor = "rgb(221 243 228)";
const backgroundColor = "rgb(24 121 78)";
const message = "Astro is awesome!";
---
<style define:vars={{ textColor: foregroundColor, backgroundColor }}>
  h1 {
    background-color: var(--backgroundColor);
    color: var(--textColor);
  }
</style>

<script define:vars={{ message }}>
  alert(message);
</script>

Caution

Using define:vars on a <script> tag implies the is:inline directive, which means your scripts won’t be bundled and will be inlined directly into the HTML.

This is because when Astro bundles a script, it includes and runs the script once even if you include the component containing the script multiple times on one page. define:vars requires a script to rerun with each set of values, so Astro creates an inline script instead.

For scripts, try passing variables to scripts manually instead.

Advanced Directives

Section titled Advanced Directives

is:raw

Section titled is:raw

is:raw instructs the Astro compiler to treat any children of that element as text. This means that all special Astro templating syntax will be ignored inside of this component.

For example, if you had a custom Katex component that converted some text to HTML, you could have users do this:

---
import Katex from '../components/Katex.astro';
---
<Katex is:raw>Some conflicting {syntax} here</Katex>