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
| Component | What it is | Notable props |
|---|---|---|
ProductCard | A 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 |
Price | One price with its labels. | minor, currency, compareAtMinor, priceContext (anonymous, customer, email_unverified, anonymous_fallback) |
Money | An amount drawn by formatMoney. | minor, currency, compareAtMinor |
StarRating | A rating as five stars, one image to a screen reader. | value, count, size |
Badge, Swatch | A label; a colour or texture dot. | kind, tone; value, hex, image, selected, disabled |
Image | A picture that reserves its space. | src, alt, aspectRatio (required), sizes, srcSet, priority, eager |
RichText | Catalog HTML through an allow-list: no script, style, event handler or javascript: URL. | html |
Link | A 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.
| Prop | Meaning (default: the catalog setting) |
|---|---|
source | { kind: 'all' }, or collection, category, tag with a handle, or search. |
initialData | The server answer (loadShopAll). No request on mount. |
filterLayout | sidebar, 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. |
pagination | numbered, load_more or infinite. |
columns | { desktop, mobile } |
priorityCount | How 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, cardMeta | How the cards are drawn; the line above each title (brand or category). |
baseUrl, jsonLd | Absolute 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 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.
priceContextsays 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
sizesfollows the layout's own column widths by default. If your CSS sets other widths, passgallerySizestoProductPage(orsizestoProductPage.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 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.
| Component | What it shows |
|---|---|
CollectionShelf | A collection's first products under its title, as a grid or a carousel, with View all. handle, eyebrow, limit, layout. |
ProductCarousel | Products 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. |
FeaturedProduct | One product shown large. layout image-left, image-right or stacked. |
CategoryDirectory | The category tree as a grid or list of links. parent, depth, showImages, showCounts. |
ReviewsList | The latest reviews of a product, or ones you choose. |
// 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 hook | What it does |
|---|---|
CartButton, CartDrawer | The 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. |
QuickAdd | A one-click add for a one-variant product; an options panel for the rest. See the Tab behaviour in the overview. |
QuickView | A 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.
// 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
| Export | Use |
|---|---|
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, robotsForShopQuery | URL state helpers, also on the /server entry. |
productMetadata, shopAllMetadata, searchMetadata, productJsonLd, breadcrumbJsonLd, itemListJsonLd | SEO builders, also on the /server entry. |
STOREFRONT_PART_KEYS, SYNC_ATTRIBUTES, GA4_EVENTS | The part keys, the data attributes a sync test reads, the analytics event names. |
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.