Components

A component is just an HTML file in components/. You use it from a template by writing its filename as a hyphenated custom-element tag. So components/hero-banner.html is used as <hero-banner>. (The hyphen is required: it is what makes it a custom element rather than an unknown HTML tag.)

Props and slots

Pass values in as attributes and read them inside the component as {tokens}, exactly like a template reads a content field:

<!-- components/hero-banner.html -->
<section class="hero">
  <h1>{heading}</h1>
  <p>{tagline}</p>
  <slot></slot>
</section>

Used in a template, with the attribute values coming from the page's fields:

<hero-banner heading="{title}" tagline="{standfirst}">
  <a href="/start">Get started</a>
</hero-banner>

Children you put between the tags fill the component's <slot>, the standard web mechanism. A component can have a default slot and named ones (<slot name="aside">, filled by slot="aside" on a child). A component that is just a slot is, in effect, a layout.

Compile-time only

Components are resolved when the site compiles: each tag is replaced by its HTML with the props filled in. Nothing about components survives into the published page, there is no runtime, no JavaScript shipped for them. It is the same idea as a function call, done at build time.

Who writes them, and where they work

Components are part of the template layer, so they are a developer's tool and need the developer role to edit (the same as templates and public/ files). They are used inside templates.

One thing to know: a component tag only expands in a template, not inside a page's rich-text body. If you type <hero-banner> into a blog post body it will not expand, body content is treated as trusted HTML, not re-compiled as a template. If you want a reusable block available to authors within prose, a developer builds it into the page template instead. For adding code to a post body, see Adding code.