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 RulesFor a template directive to be valid, it must:
- Include a colon
:
in its name, using the formX:Y
(ex:client:load
). - Be visible to the compiler (ex:
<X {...attr}>
would not work ifattr
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 Directivesclass:list
Section titled class:listclass: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 elementclass
Object
: All truthy keys are added to the elementclass
Array
: flattenedfalse
,null
, orundefined
: skipped
set:html
Section titled set:htmlset: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.
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.
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.
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.
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.
define:vars
Section titled define:varsdefine: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()
.
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 Directivesis:raw
Section titled is:rawis: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:
Reference