Building
Components
Named subtrees with typed props, emitted as real .astro files.
A component is a named subtree with typed properties, emitted as a real .astro file. It is the first answer to "I need this twice".
Making one
Select a subtree in the tree, right-click, Create component. It is replaced in place by an instance — the page now points at the component instead of holding a copy of its markup.
Open a component to edit it and the canvas switches to the component itself, with a breadcrumb back to the page. Opening a component from inside another one is not a one-way door; every step in the trail is a way back.
Properties
Declared in the Properties tab while you are editing the component, filled per instance in the Settings tab. Write {propName} in text or in an attribute and it becomes a real Astro prop:
---
interface Props { title: string; body: string; href: string; }
const { title, body, href } = Astro.props;
---
<a builder-data-element="link" class="feature-card" href={href}>
<h3 builder-data-element="heading" class="feature-card__title">{title}</h3>
<p builder-data-element="text" class="feature-card__body">{body}</p>
</a>Types: text, number, boolean, url, select (with options), media, class, loop, object, condition and group. Each one changes the control an instance gets and how the value is emitted — a number stays a number, a boolean becomes a bare attribute or false, a media prop opens the media picker.
A prop with a default is what an instance uses when it leaves the field empty.
A component travels whole
It carries its own stylesheet and its own script, exactly like an .astro file:
- Styles emit as a
<style>block, which Astro scopes to this component's markup. - Script emits as a
<script>, which Astro bundles once per page however many instances there are — so query all of them, do not assume one.
Drop the component on a page that has never seen it and it still looks right.
A class you want to use outside the component belongs in a global stylesheet. Astro's scoping means a component's own styles apply to its own markup and nothing else.
Using one
Instances appear in the insert menu under your components. On the page an instance is one node with a component reference and its prop values — no copy of the markup, so a change to the component reaches every instance at once.
Emitted, that is an import and a tag:
---
import FeatureCard from '../components/FeatureCard.astro';
---
<FeatureCard title="Fast" body="Zero JavaScript by default." href="/speed" />When to use what
| You have | Use |
|---|---|
| A card, a feature row, a CTA, a testimonial | a component |
| A header, a footer, anything around the page | a template |
| A tracking script, a font link, a bit of CSS on some routes | a snippet |
| A class more than one page needs | a global stylesheet |
The rule of thumb: when you catch yourself building the same subtree twice, stop and make it a component. Two copies is the moment they start drifting apart.