Building pages
Sections
A section is a widget tree with a name. Heroes, catalog grids, the header, the product page: all of them are built from the same widgets as everything else, so all of them can be edited the same ways.
Anatomy
The root of a section is a Container whose slot starts with section:. Inside, named slots mark the parts the builder manages. This is the Categories section, trimmed a little:
<Container slot="section:categories">
<Container slot="inner" className="py-12 px-6" maxWidth="var(--container-width, 1280px)" centered>
{categories({ topLevel: true, limit: 8 }) && (
<Column slot="content" className="items-stretch gap-8">
<Text slot="heading" className="text-[28px] text-gray-900 text-center" semanticsTag="h2">
Shop by category
</Text>
<GridView slot="items" className="grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
{categories({ topLevel: true, limit: 8 }).map((item) => (
<Card slot="item" className="m-0 bg-white rounded-xl shadow-none">
<Link href={item.url}>
<Column className="items-stretch">
<AspectRatio slot="frame" className="aspect-square">
<Image slot="image" className="w-full h-full object-cover" src={item.image} hoverZoom />
</AspectRatio>
<Padding slot="label" className="p-4">
<Text slot="name" className="text-[12px] text-gray-700 text-center truncate">
{item.name}
</Text>
</Padding>
</Column>
</Link>
</Card>
))}
</GridView>
<Row className="justify-center">
<FilledButton slot="cta" label="View all" onPressed={{ type: "url", url: "/category" }} />
</Row>
</Column>
)}
</Container>
</Container>section:categoriestells the builder what this is, so it offers the right tools.innerholds the section's width and spacing;contentits column.heading,items,itemandctaare what the section's tools edit: the title, the grid, the card template and the View all button.- The list guards the content, so a store with no categories shows no empty heading.
Section kinds
| Slot | What it is |
|---|---|
section:hero | A full-width banner: heading, description, button, background image or video. |
section:hero-carousel | A Carousel of hero slides. |
section:categories | A grid of categories from categories({ … }). |
section:brands | A grid of brands from brands({ … }). |
section:collections | A grid of collections from collections({ … }). |
section:featured-products | A grid of product cards, newest or hand-picked. |
section:products-grid | A grid of products from one category, brand or collection. |
section:similar-products | On the product page: products({ similar: true }). |
section:products-listing | The Products page: filter bar, results grid and pagination. |
section:product-detail | The product page body: gallery, details, variants and add to cart. |
section:checkout | The checkout page: heading around the checkout form. |
The header and footer work the same way. They keep their own shell for settings like a sticky header, and their parts are widgets: the logo is a Link with slot section:logo, footer columns are Columns of links, and the copyright is a Text using {year}.
Header sub-links
A link in the header's navigation can hold sub-links: a dropdown on desktop, and an accordion in the mobile menu. Shop templates use this to list their categories, brands and collections, and blog templates to list their tags.
The menu fills in Categories, Brands and Collections from your catalog when you have more than one of each.
Card padding and corners
When a design rounds the corners of product, category, brand and collection cards, their text moves in to clear them: at least 12px from 8px corners, and about three-quarters of the radius on rounder ones, up to 28px. Sharper corners keep a flush caption, and padding is only ever raised. It's set when a card is built or a design is applied, so re-apply your aesthetic to update existing pages. After that, set a card's padding however you like.
Tools and code agree
Select anything inside a section and its tools appear: pick items or switch to automatic, set the number of columns, change the card layout, show or hide View all. Each tool edits the same tree the code shows. Pick three brands in the panel and the code reads brands({ ids: ["nike", "adidas", "puma"] }); type that yourself and the panel shows those three picks.
Store behaviour inside sections
Some parts of a store do more than show data: the product gallery, the variant picker, quantity and add to cart, the listing filters and pagination, the checkout form, the cart and account icons. These are single elements that sit inside the widget tree. You place, space and style them like any widget (put the price above the title, or the gallery on the right); their behaviour comes with them.
Writing your own
Any widget tree can be a section. Build it in code, save the layer, and it lives on the page like the built-in ones. A section: slot is only needed when you want one of the built-in kinds and its tools.
The AI button writes sections in this language too. It sees the same widgets, data calls and slots described in this guide, and the editor checks its code before it reaches your page. Use the syntax rules to read or adjust what it produced.