Building a component

Build Visually in the Components tab opens a blank component in Creative Mode — the same tree, inspector, styling panel and CSS box that edit a page. Convert to Component then writes it out as a real .astro file with a typed Props interface.

Starting

The document arrives with a <section> carrying the component’s BEM root class. The block convention is put there at the start rather than policed at the end.

From there it is ordinary Creative Mode. Add elements, style them, write the CSS — everything works because the draft is a plain HTML fragment and a plain stylesheet, which is exactly what Creative Mode natively produces.

Props are found, not declared

Type {heading} where the value goes. That is the declaration.

There is no prop panel to keep in step with the markup, because there is nothing to keep in step — the literal in the tree is the only record. The { } button in the element toolbar and Prop in the touch bar both simply put one where the cursor is.

The Inspector lists every prop the component contains, renames one in place across the whole tree, and is where demo content goes.

Convert to prop

Write the real wording first — it is the only way to see whether a block works — then turn it into a prop in one click.

The Inspector suggests a name from what you already called the element, so .banner__heading becomes heading. It keeps your wording as the prop’s demo content and puts {heading} in the markup. Nothing is retyped.

Demo content

Give heading something like Our Services and the preview shows that rather than {heading}.

A component full of braces tells you the contract and nothing at all about the spacing, and spacing is most of what you are looking at while you build one.

On conversion the demo content becomes that prop’s default, so the component renders standalone and a page that passes nothing still gets something. A prop with no demo content stays required.

The draft on disk always holds the prop, never the demo value.

Frontmatter

A frontmatter editor sits in the HTML pane bar — the same editor the <head> button opens in Full HTML mode. Imports, constants, anything that runs before the markup, kept verbatim.

The generated destructure is placed above your code, so your code can use the prop names. Write your own interface Props and yours is kept; nothing is generated over the top of it.

The draft

A component in progress is a real thing on disk, at component-drafts/<Name>/ in the project root — outside src/, so Astro never sees it.

It saves on the same rhythm as everything else you type. Close it and the draft stays. The Components tab lists your drafts above your components, and opening one picks up where you left off, including after a restart.

Converting clears the draft away. Deleting one sends it to the trash rather than destroying it.

Converting

The dialog shows the whole of it before anything is written: the props it found and where each is used, the files it will create, the finished file, and anything it thinks is off — a brace that is not a prop name, a second <h1>, an outermost element that is not a <section>.

Those are said, not enforced. It is your component.

A folder or a single file

You choose. A folder keeps the stylesheet beside the .astro. A single file keeps the rules inside it, in a <style> block that Astro scopes to that component on its own.

Neither is more correct. A folder suits a component whose CSS you expect to keep working on; one file suits a component that is finished.

Classes you created but never styled are left out of the stylesheet rather than written as empty rules.

Where it puts you afterwards

Back on the page you were working on — not inside the component, which has no address of its own to preview, and not out to the welcome screen, which would drop you out of the project altogether.

If you opened the creator from the welcome screen and then discarded it, there is no page behind it, and FEWD shows you the way back rather than leaving an empty tree and an empty preview.

Conversion only ever creates

It will not write over a component that is already there, and it is never handed an existing .astro file and asked to update it.

A file that does not exist yet cannot be corrupted, which is the whole of the safety argument here. Conversion is one way, and the dialog says so.

If you need to change a converted component, change the .astro file — in Framework Mode, with the styling panel, like any other file in the project.

Using it on a page

Open the page and type < and the component’s first letter. It appears in the list — FEWD walks the project for components rather than only offering ones already imported — and accepting it writes both the tag and the import, with the right relative path.

Then typing inside the tag offers the component’s own props, read from the Props interface conversion generated. See An Astro site, end to end.

One thing worth knowing about props in attributes

FEWD quotes every attribute, so alt={caption} would come back out as alt="{caption}" — which in Astro is five literal characters that render on the page.

The emitter has a special case for it: a value that is wholly one prop is written unquoted. It goes the other way too, and braces in ordinary copy are escaped, because a bare { opens an expression and {} in a code sample would otherwise be a compile error rather than two characters.

Neither has a symptom until somebody reads a rendered page, which is why it is mentioned here.