The language
Store data
Point at your catalog instead of copying from it. Data is read when the page is served, so prices, stock and images are always current.
Reading a value
Put a data path in braces, as a Text's content or as a prop value. On a product page, product is the product being viewed:
<Column className="gap-2">
<Text semanticsTag="h1">{product.name}</Text>
<Text className="text-xl font-semibold">{product.price}</Text>
<Text className="text-sm text-gray-500">{product.brand.name}</Text>
</Column>Data can sit between words in the same text:
<Text className="text-sm text-gray-500">By {product.brand.name}</Text>What's available where
| Name | Available |
|---|---|
product | Anywhere on the product page |
item (or the name you choose) | Inside a .map(): the current item. See Lists & conditions |
listing | Inside the products listing section: listing.products is the current page of results, after filters |
category("…") and friends | Anywhere: look up one item by slug |
products({ … }) and friends | Anywhere: a list from your catalog |
Using a name that isn't available where you are gives a warning listing the ones that are:
WarningUnknown data "prodct" — available here: product, theme
Fields
| Type | Fields |
|---|---|
| Product | idnameslugdescriptionshortDescriptionpricecompareAtPriceonSaleinStockimageimagesbrandurlhasOptionsvariantId |
| Category | idnameslugdescriptionimageurlproductschildren |
| Brand | idnameslugdescriptionimagelogourlproducts |
| Collection | idnameslugdescriptionimageurlproducts |
Fields chain: product.brand.name, category("shoes").children. price and compareAtPrice arrive formatted in the store's currency. url is the item's page on the storefront, ready for a link. The editor completes field names as you type.
One item by slug
category("slug"), product("slug"), brand("slug") and collection("slug") fetch one item. The slug is the one shown in your dashboard.
<Column className="gap-2">
<Text semanticsTag="h2">{category("running-shoes").name}</Text>
<Text>{category("running-shoes").description}</Text>
</Column>Slugs are checked against your catalog as you type. A typo is an error that names the closest match, and pointing at a draft or inactive item is a warning, since visitors won't see it:
ErrorNo category with slug "runing-shoes" — did you mean "running-shoes"?
Lists
Four calls return lists, which you repeat with .map(). Each takes one options object:
| Call | Options |
|---|---|
products({ … }) | categorybrandcollectionsearchsimilaridslimitsort |
categories({ … }) | topLevelidslimitsort |
brands({ … }) | idslimitsort |
collections({ … }) | idslimitsort |
limit- How many items, at most.
sort"newest","oldest","name_asc","name_desc", or"manual"(categories keep the order set in your dashboard; others sort by name).ids- Hand-picked items by slug. They come back in the order you list them.
category,brand,collection- Products in that category, brand or collection (by slug).
search- Products matching a search term.
similar: true- On a product page: products like the one being viewed. It tries the same brand, then the same category, then the rest of the catalog, and never includes the product itself.
topLevel: true- Only categories without a parent.
<GridView className="grid-cols-2 md:grid-cols-4 gap-4">
{products({ category: "running-shoes", sort: "newest", limit: 8 }).map((item) => (
<Link href={item.url}>
<Column className="gap-2">
<AspectRatio className="aspect-square">
<Image src={item.image} className="w-full h-full object-cover" />
</AspectRatio>
<Text className="text-sm truncate">{item.name}</Text>
<Text className="text-sm font-semibold">{item.price}</Text>
</Column>
</Link>
))}
</GridView><Row className="gap-6 justify-center">
{brands({ ids: ["nike", "adidas", "puma"], sort: "manual" }).map((item) => (
<Link href={item.url}>
<Image src={item.image} height={48} semanticLabel={item.name} />
</Link>
))}
</Row><GridView className="grid-cols-2 lg:grid-cols-4 gap-4">
{products({ similar: true, limit: 4 }).map((item) => (
<Text>{item.name}</Text>
))}
</GridView>A misspelt option is an error that lists the valid ones:
ErrorUnknown option "limt" — use category, brand, collection, search, similar, ids, limit, sort
Framing images
Product photos come in every shape. To keep a grid of cards even, frame each image in an AspectRatio and let the image fill it with w-full h-full object-cover, as in the grid above. The shape belongs to the frame, not the image, so aspect-* on an Image is an error that points you to the frame:
<Image src={product.image} className="aspect-square object-cover" />ErrorImage has no aspect ratio — wrap it in an <AspectRatio>
Placeholders in text
Footers can write {year} inside a data string. It's replaced with the current year, so the copyright line never goes stale.
<Text className="text-xs text-gray-500 text-center" data="© {year} Steppers. All rights reserved." />