Product Catalog / Storefront components

Components

Every public export has a JSDoc comment, so your editor shows what each prop does on hover; this page is the map of what exists. All of them take classNames (class names per part key), className (the root) and unstyled, and read their defaults from your catalog settings (a prop wins over the setting, the setting over the package default).

Money is always formatted for you

Components show every amount with formatMoney from @usethrottle/money, in the record's own currency. A slot that draws a price receives minor (the amount in the currency's minor units) and currency, never a pre-formatted string, and must call formatMoney(minor, currency). Do not divide by 100, call toFixed(2), use Intl currency styles, hard-code a symbol or default to USD. Catalog answers also carry ready-made display strings where a read gives them.

Pieces

ComponentWhat it isNotable props
ProductCardA product in a list: picture, title, price, rating, badges, quick add.product, generatedAt (required, ISO: the new badge ages against it, never the browser clock), variant (standard, minimal, overlay, row), meta (brand or category), position, listName, slots, onSelect
PriceOne price with its labels.minor, currency, compareAtMinor, priceContext (anonymous, customer, email_unverified, anonymous_fallback)
MoneyAn amount drawn by formatMoney.minor, currency, compareAtMinor
StarRatingA rating as five stars, one image to a screen reader.value, count, size
Badge, SwatchA label; a colour or texture dot.kind, tone; value, hex, image, selected, disabled
ImageA picture that reserves its space.src, alt, aspectRatio (required), sizes, srcSet, priority, eager
RichTextCatalog HTML through an allow-list: no script, style, event handler or javascript: URL.html
LinkA link through the store link component (a plain anchor, or next/link).href, prefetch, any anchor attribute

Reserved for a later release, rendering nothing today so a slot can already name them: WishlistButton, BackInStock, FrequentlyBoughtTogether, ReviewPhotos, ReviewVotes, QuestionsAndAnswers.

Shop

ShopAll is the listing page for the shop, a collection, a category, a tag or a search: heading, controls, filters, grid and pagination, laid out by your settings. Give it initialData from loadShopAll and it renders at once and fetches nothing until the shopper changes the selection. With children it is ShopAll.Root around them, so you lay the pieces out.

PropMeaning (default: the catalog setting)
source{ kind: 'all' }, or collection, category, tag with a handle, or search.
initialDataThe server answer (loadShopAll). No request on mount.
filterLayoutsidebar, topbar or drawer. The markup carries the sidebar and the Filters button; CSS shows the right one by width, so the server paint is already right.
paginationnumbered, load_more or infinite.
columns{ desktop, mobile }
priorityCountHow many cards, from the first, load their picture at once. The first is the page's largest paint (high priority, preloaded in the HTML), the rest of the row load at once at low priority, so they do not compete with it, later cards are lazy. Default: the desktop row size; 0 leaves all lazy.
cardVariant, cardMetaHow the cards are drawn; the line above each title (brand or category).
baseUrl, jsonLdAbsolute URLs for the JSON-LD; turn the JSON-LD off if you render it yourself.

The pieces on ShopAll: Root, Heading, Breadcrumbs, FilterSidebar, FilterBar, FilterDrawer, ActiveFilters, SortSelect, ResultCount, ProductGrid, Pagination, SlotAbove, SlotBelow. FacetGroup draws one filter (checkboxes, colour swatches, a dropdown, a yes or no choice, or a numeric range; values OR within a filter and AND across filters). useShopAll() answers the state and actions (see Recipes).

A hand-built shop page
// A shop page laid out by hand: the filters in a top bar, the sort beside the count, no sidebar.
import { ShopAll } from '@usethrottle/storefront-react';

export function ShopPage() {
  return (
    <ShopAll.Root source={{ kind: 'all' }} filterLayout="topbar" pagination="load_more" columns={{ desktop: 4, mobile: 2 }}>
      <ShopAll.Breadcrumbs />
      <ShopAll.Heading />
      <ShopAll.SlotAbove />
      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
        <ShopAll.ResultCount />
        <ShopAll.SortSelect />
      </div>
      <ShopAll.FilterBar />
      <ShopAll.ActiveFilters />
      <ShopAll.ProductGrid />
      <ShopAll.Pagination />
      <ShopAll.SlotBelow />
    </ShopAll.Root>
  );
}

Product page

ProductPage is the whole page: breadcrumbs, the gallery and buy box in the layout (classic, stacked or editorial), the sections (tabs, accordions or a stack), related products, reviews and the sticky add bar. Give it initialData from loadProduct. With children it is ProductPage.Root; the pieces are JsonLd, Breadcrumbs, SlotAbove, Gallery, BuyBox, VariantPicker, Price, StockStatus, QuantityInput, AddToCart, StickyAddToCart, ProductSections, ShippingSection, TagList, CategoryList, RelatedProducts, Reviews, ReviewForm, SlotBelow. useProductPage() answers the product, the chosen variant and options, stock, the quantity and add().

  • The price shown is the chosen variant's own; it is never computed in the browser. priceContext says whose price it is.
  • Choosing an option that does not go with the other choices lands on the nearest variant that has it. Quantity is held to 1 and the variant's maximum.
  • reviewsLayout="columns" puts the summary and histogram beside the list from 768 px.
  • The gallery's sizes follows the layout's own column widths by default. If your CSS sets other widths, pass gallerySizes to ProductPage (or sizes to ProductPage.Gallery), so a phone fetches the smallest file that fills the photo. The shown photo is always eager and high priority.
  • The shipping section reads a catalog content page by handle (a store without a Builder).
A hand-built product page
// A product page with your own arrangement inside the page's state: one gallery, then the buy box,
// the sections, related products and reviews.
import { ProductPage } from '@usethrottle/storefront-react';
import type { ProductData } from '@usethrottle/storefront-react/server';

export function Product({ data }: { data: ProductData }) {
  return (
    <ProductPage.Root initialData={data} baseUrl="https://shop.example" reviewsLayout="columns">
      <ProductPage.JsonLd />
      <ProductPage.Breadcrumbs />
      <ProductPage.SlotAbove />
      <ProductPage.Gallery />
      <ProductPage.BuyBox headingLevel={1} />
      <ProductPage.ProductSections />
      <ProductPage.RelatedProducts />
      <ProductPage.Reviews />
      <ProductPage.SlotBelow />
      <ProductPage.StickyAddToCart />
    </ProductPage.Root>
  );
}

Frame

StoreFrame wraps every page: a skip link, the announcement bar, Header, <main id="main-content"> and Footer. Its header and footer props take the props of those components: the footer's brand block is drawn before the menu and its children between the menu and the copyright line (a newsletter form, social links). The header's slots replace SearchBox, AccountButton, CartButton, CategoryNav, LocaleSwitch or CurrencySwitch; the language and currency switches appear only when you give the header onLocaleChange or onCurrencyChange (changing currency moves the cart, so the handler may be async). The menus, announcement and copyright text come from the site design.

Merchandising

For home and content pages. Give each initialData from loadMerchProducts (or loadProduct) and the first render has its products and makes no request; without it they are read in the browser and kept for an hour.

ComponentWhat it shows
CollectionShelfA collection's first products under its title, as a grid or a carousel, with View all. handle, eyebrow, limit, layout.
ProductCarouselProducts from a source (a collection, category or tag, featured, newest or best rated, or a list of handles) in a scrolling row. source, title, eyebrow, limit.
FeaturedProductOne product shown large. layout image-left, image-right or stacked.
CategoryDirectoryThe category tree as a grid or list of links. parent, depth, showImages, showCounts.
ReviewsListThe latest reviews of a product, or ones you choose.
A shelf and a carousel on the home page
// A home page section: a collection shelf and a product carousel. Give each `initialData` from
// `loadMerchProducts` on the server and it renders at once and asks for nothing.
import { CollectionShelf, ProductCarousel } from '@usethrottle/storefront-react';
import { createStorefrontServerClient, loadMerchProducts } from '@usethrottle/storefront-react/server';

export async function Home() {
  const client = createStorefrontServerClient({ catalogKey: process.env.THROTTLE_CATALOG_SERVER_KEY ?? '' });
  const shelf = await loadMerchProducts({ client, source: { kind: 'collection', handle: 'summer' }, limit: 4 });
  const newest = await loadMerchProducts({ client, source: { kind: 'newest' }, limit: 8 });
  return (
    <>
      <CollectionShelf handle="summer" eyebrow="New in" limit={4} layout="grid" initialData={shelf} />
      <ProductCarousel source={{ kind: 'newest' }} title="Just arrived" limit={8} cardMeta="category" initialData={newest} />
    </>
  );
}

Shopper tools

Component or hookWhat it does
CartButton, CartDrawerThe cart button with its unit count, and the drawer it opens (or inline for a cart page). Lines, subtotal and a checkout button; checkoutUrls sets where checkout returns. useCartDrawer() opens it from your own button.
QuickAddA one-click add for a one-variant product; an options panel for the rest. See the Tab behaviour in the overview.
QuickViewA dialog with the product's buy box over a list. handle, open, onOpenChange.
CompareButton, Compare, useCompare()Compare two to four products. Only handles are kept, in the browser.
RecentlyViewed, useRecentlyViewed()The last products looked at, as cards (up to 12). Only handles are kept, in the browser.

Pages

SearchResults is the search page (q, initialData from loadSearch); NotFound is the 404 page, its own <main> except inside StoreFrame; AccountPage is on the /account entry.

Slots

Replace a piece of a component with the slots prop. A slot receives the props its default takes, so a replacement is a drop-in. ProductCard takes Image, Title, Price, Rating, Badges, QuickAdd and WishlistButton; BuyBox takes Price, VariantPicker, StockStatus, QuantityInput, AddToCart, WishlistButton and BackInStock; Header takes the six pieces above.

Replace the Price slot
// Swap the Price slot of every card. The slot receives the amounts in minor units and the record's own
// currency; show them with formatMoney, never with your own division or a currency symbol.
import { formatMoney } from '@usethrottle/money';
import { ProductCard, type PriceProps } from '@usethrottle/storefront-react';
import type { ListProduct } from '@usethrottle/catalog';

function MemberPrice({ minor, currency, compareAtMinor, priceContext }: PriceProps) {
  return (
    <p data-price-context={priceContext}>
      <strong>{formatMoney(minor, currency)}</strong>
      {compareAtMinor !== undefined && compareAtMinor > minor ? <s> {formatMoney(compareAtMinor, currency)}</s> : null}
    </p>
  );
}

export function Card({ product, generatedAt }: { product: ListProduct; generatedAt: string }) {
  return <ProductCard product={product} generatedAt={generatedAt} slots={{ Price: MemberPrice }} />;
}

Separate from these, SlotOutlet marks places where a host (the Throttle Builder) may add content: product.above, product.below, shop.above and shop.below. With no host an outlet renders nothing, not even its wrapper. See Theming.

Hooks and helpers

ExportUse
useStorefront()Everything the provider resolved: settings, site design, preset, locale, currency, client, router, analytics. Throws outside the provider.
useStrings(){ t, keyAttr }: text by key, through the string precedence.
usePart(key, local?)The attributes of one part (class and data-throttle-part), for your own components.
useTrack()Send an analytics event through the provider.
useShopAll(), useProductPage()The state of the nearest ShopAll.Root or ProductPage.Root. Both throw outside one.
useMerchProducts(), useRelatedProducts()The reads behind the merchandising and related components.
parseShopQuery, shopQueryToSearch, shopListQuery, canonicalForShopQuery, robotsForShopQueryURL state helpers, also on the /server entry.
productMetadata, shopAllMetadata, searchMetadata, productJsonLd, breadcrumbJsonLd, itemListJsonLdSEO builders, also on the /server entry.
STOREFRONT_PART_KEYS, SYNC_ATTRIBUTES, GA4_EVENTSThe part keys, the data attributes a sync test reads, the analytics event names.
Sync attributes
Components emit the data attributes an automated sync test reads (for example data-product-card, data-product-handle, data-badge, data-string-key), so a store built on them can be tested against catalog changes without custom markup. The list is SYNC_ATTRIBUTES.