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

NameAvailable
productAnywhere on the product page
item (or the name you choose)Inside a .map(): the current item. See Lists & conditions
listingInside the products listing section: listing.products is the current page of results, after filters
category("…") and friendsAnywhere: look up one item by slug
products({ … }) and friendsAnywhere: 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

TypeFields
ProductidnameslugdescriptionshortDescriptionpricecompareAtPriceonSaleinStockimageimagesbrandurlhasOptionsvariantId
Categoryidnameslugdescriptionimageurlproductschildren
Brandidnameslugdescriptionimagelogourlproducts
Collectionidnameslugdescriptionimageurlproducts

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:

CallOptions
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.
The eight newest running shoes
<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>
Three hand-picked brands, in this order
<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>
On the product page: You may also like
<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:

Won't parse
<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." />