Product Catalog

Storefront components

@usethrottle/storefront-react is a set of React components for a Throttle product catalog: the shop and collection listing, the product page, search, the cart drawer, the account page and the page frame around them. They read their display (menus, filters, sorts, badges, theme, text) from your catalog's storefront settings, so a store needs a few lines and most changes are made in the dashboard, not in code.

Start

  • A new Next.js store: run npx @usethrottle/create-store my-store. See create-store.
  • An existing app: install the package, wrap the app in StorefrontProvider and render a component. See below.
  • Next.js specifics: route helpers, caching and the hosting-cost rules are on Next.js and caching. Read the cost section before you deploy.

Install

Install
# A new Next.js store, with both keys asked for:
npx @usethrottle/create-store my-store

# Add the package to an existing app instead:
pnpm add @usethrottle/storefront-react @usethrottle/catalog @usethrottle/money

The package needs @usethrottle/catalog ^1.4.1, @usethrottle/money ^1.1.0, and React 18 or newer. Next.js >=15, @usethrottle/scripts and @usethrottle/auth are optional peers (auth is read only by the ./account entry). Your app and the package must resolve one copy of @usethrottle/catalog and of react; two copies are two React contexts, and each reads a different cart. Check with pnpm why @usethrottle/catalog.

EntryWhat it holds
@usethrottle/storefront-reactThe components and hooks (client).
@usethrottle/storefront-react/serverLoaders, metadata and JSON-LD builders, the server catalog client. No React.
@usethrottle/storefront-react/nextNext.js route helpers and the signed revalidate and sync handlers. Server only.
@usethrottle/storefront-react/next/clientStorefrontNextProvider, the provider wired to Next's router and links.
@usethrottle/storefront-react/accountAccountPage. Needs @usethrottle/auth.
@usethrottle/storefront-react/styles.cssThe same stylesheet as a file, for a cached, flash-free server render (with injectStyles false).

Two catalog keys: browser and server

A catalog has two kinds of key, and a store uses both. They are not interchangeable.

KeyVariableUsed by
Browser keyNEXT_PUBLIC_THROTTLE_CATALOG_KEYThe provider in the browser. It is public by design, and the catalog answers it only from the websites you allowed: add your https origin to the key's allowed websites in the dashboard.
Server keyTHROTTLE_CATALOG_SERVER_KEYYour server: loaders, route helpers, the sync handler. A request from your own server carries no website origin, so the catalog refuses a browser key there (403 ORIGIN_NOT_ALLOWED). It also works for local development.
.env.local
# .env.local
# Browser key: sent to the browser. The catalog answers it only from your allowed websites.
NEXT_PUBLIC_THROTTLE_CATALOG_KEY=pc_pk_...
# Server key: your server reads with it. NEVER a NEXT_PUBLIC_ variable.
THROTTLE_CATALOG_SERVER_KEY=pc_pk_...
NEXT_PUBLIC_SITE_URL=https://shop.example
THROTTLE_WEBHOOK_SECRET=whsec_...
Never put a server key in a NEXT_PUBLIC variable
A NEXT_PUBLIC_ variable is written into the JavaScript your visitors download. The catalog refuses a server key on a browser request (403 SERVER_KEY_IN_BROWSER), but the key is still exposed. Keep it in a plain variable on your host, and never use a secret (pc_sk_) key in a storefront. See Keys and channels.

Quick start

A client-only app (Vite, for example) needs a provider and a component. The provider reads your catalog's settings in the browser, and the history router is its default.

src/App.tsx
// src/App.tsx of a Vite (client-only) app: no server, no Next.js.
// main.tsx renders it with createRoot(document.getElementById('root')!).render(<App />).
import { CartDrawer, ShopAll, StoreFrame, StorefrontProvider } from '@usethrottle/storefront-react';
import '@usethrottle/storefront-react/styles.css';

// Keep the cart's session id in the browser, so a reload keeps the cart.
const cartStorage = {
  get: () => localStorage.getItem('throttle-cart'),
  set: (id: string) => localStorage.setItem('throttle-cart', id),
  remove: () => localStorage.removeItem('throttle-cart'),
};

export function App() {
  return (
    // The browser key is public: your site's origin must be one of its allowed websites.
    <StorefrontProvider
      catalogKey="pc_pk_your_browser_key"
      preset="editorial"
      locale="en"
      currency="USD"
      cartStorage={cartStorage}
    >
      <StoreFrame>
        <ShopAll source={{ kind: 'all' }} />
      </StoreFrame>
      <CartDrawer />
    </StorefrontProvider>
  );
}

For Next.js, give the provider the settings the server already loaded (loadSettings) so the first paint needs no request, and use StorefrontNextProvider. The route files are three lines each; see Next.js and caching.

StorefrontProvider

One provider holds everything the components share: the catalog client and its settings, the resolved site design (theme, brand, menus), the router, the link component, analytics, the cart drawer and your text overrides.

PropMeaning
catalogKeyThe browser key. Give this or client.
clientA ready catalog client (a server-built one, or a fixture in tests).
settingsThe settings answered on the server (loadSettings). The first render uses them with no request.
preset, theme, schemeThe look. See Theming.
locale, currency, dirLanguage and currency for the reads. dir defaults from the locale (right to left for Arabic, Hebrew and the like).
appearanceparts (class names per part), variables and darkVariables (token overrides, the last word).
localizationText overrides for any string, in any language.
analyticsWhere GA4-shaped events go. See Analytics.
router, linkComponentHow the URL is read and links are drawn. StorefrontNextProvider sets both.
customerKey, customerCart, cartStorage, cartUrlsCart wiring. See One cart.
generationWatchThe open tab's check for a catalog change. Default on, every 60 s at the least; false turns it off.
injectStylesDefault true: the provider renders the stylesheet in its own markup, so it is in the HTML the server sends and the first paint is styled (the client adopts it, no second copy). Set false and import styles.css yourself to ship it as a cached file instead.
imageOriginWhere catalog media is requested. Every image URL whose path starts with /media/ (cards and the gallery) is requested at <imageOrigin>/media/...; '' is your own origin, so a rewrite of /media/:path* to the catalog saves the phone a second connection. Default: the catalog's URLs.

One cart

StorefrontProvider creates the one CatalogProvider of your app. The add-to-cart buttons, the cart button and the drawer read the same cart as your own useCart() from @usethrottle/catalog/react. Hand the cart wiring to the storefront provider and it forwards it unchanged:

  • cartStorage: where the cart session id is kept (get, set, remove). The default is memory only, so a reload starts a new cart.
  • customerKey and customerCart: whose cart this is, and resuming a signed-in customer's cart on any device.
  • cartUrls: returnUrl, cancelUrl and storefrontUrl, sent on every cart and used by checkout(). Each is an absolute https URL on an allowed return website.
  • throttleBaseUrl and throttleCheckoutUrl: Throttle's API and hosted pages, when they are not the defaults.
Do not mount a second CatalogProvider
Two providers never share a cart: a button inside one adds to a different cart than your header's count reads. Wrap your app once, in StorefrontProvider, and call useCart() anywhere under it. The cart rules themselves (return URLs, customer carts) are on Cart and checkout and React.

What wins when sources disagree

AreaOrder, first wins
Theme (preset, tokens, colour scheme)A Throttle Builder's site design, then your preset / theme / scheme props, then the catalog's own theme, then the clean preset.
Every other site field (brand, menus, announcement, SEO defaults, site strings)The Builder, then the catalog settings, then the package defaults.
Token overridesappearance.variables and darkVariables beat every theme source, always.
Catalog display (cards, listing, filters, sorts, badges, product page)A prop on the component, then the catalog setting, then the package default.
TextThe Builder's strings, then your localization prop, then the catalog settings' strings, then the package's English.

A null in a site design is a value (it clears a field); undefined falls through to the next source. The details, with presets and slots, are on Theming.

Presets

Three presets set the colours, fonts, radius and spacing: clean (the catalog's own defaults), editorial and bold. Pick one with the preset prop or in the dashboard. Their tokens come from @usethrottle/ui/presets (PRESET_TOKENS); each package keeps its own per-preset CSS, keyed by [data-throttle-preset] on the storefront root.

Styling and the layer order

Every element carries data-throttle-part="<part-key>" and the class tsf-<part-key> (the class is dropped under unstyled). Part keys are kebab-case <component>-<part>, for example product-card-title, and are exported as STOREFRONT_PART_KEYS. They are a versioned contract: a key is never renamed in a minor release. Every component takes classNames (per part key) and className (the root); the order is the package's class, appearance.parts[key], classNames[key], then className.

The sheet is wrapped in @layer throttle with single-class selectors and logical properties only. So an unlayered rule of yours, or a Tailwind utility, wins without !important, while Tailwind's preflight reset (its base layer) cannot override the package. That relies on one line:

The layer order
@layer theme, base, throttle, components, utilities;
  • In the browser the provider declares that line itself, first in <head>. Its server-rendered sheet carries the line too, but it sits in the page body, after any layer statement already in <head> (Tailwind's): the browser corrects the order once the page hydrates. A store with Tailwind should use the next option, so the order is right from the first paint.
  • With injectStyles={false} (the Next.js setup: the sheet is a cached file and the order is right from the first byte), import @usethrottle/storefront-react/styles.css. dist/styles.css starts with that exact line, followed by the sheet, so import it before your Tailwind CSS (or any CSS that declares layers) and the order holds. If your own CSS must load first, make the same line its first line.
  • Without Tailwind the names theme, base, components and utilities are declared empty, so the order is the same and your unlayered CSS still wins over throttle.
app/globals.css (Tailwind v4)
/* app/globals.css with Tailwind v4. Declare the layer order first. `throttle` sits between Tailwind's
   `base` (its preflight reset) and `components` / `utilities`: the reset cannot undo the storefront's
   own rules, and a utility class still beats the storefront. */
@layer theme, base, throttle, components, utilities;
@import 'tailwindcss';
@import '@usethrottle/storefront-react/styles.css';
Tailwind classes per part
// Restyle with Tailwind: pass utility classes per part key. They are added after the package's own classes
// and, because the package's CSS sits in @layer throttle below `utilities`, they win without !important.
import { ProductCard, ShopAll } from '@usethrottle/storefront-react';
import type { ListProduct } from '@usethrottle/catalog';

const classNames = {
  'product-card': 'rounded-2xl shadow-sm hover:shadow-md',
  'product-card-title': 'text-base font-semibold tracking-tight',
  'shop-all-heading': 'text-4xl font-bold',
};

export function Shop() {
  return <ShopAll source={{ kind: 'all' }} classNames={classNames} />;
}

export function OneCard({ product, generatedAt }: { product: ListProduct; generatedAt: string }) {
  return <ProductCard product={product} generatedAt={generatedAt} classNames={classNames} />;
}

To draw your own markup, wrap the tree in <Unstyled> (or pass unstyled): the base classes go, data-throttle-part stays. Recipes are on Recipes.

URL state

The listing's selection lives in the URL, so it can be shared, bookmarked and used with the back button. A filter is filter.<key>=value (repeat it for several values), a range is one min..max value, plus sort, page and q (a search). A product page takes ?variant=<sku>. The server helpers parseShopQuery, shopQueryToSearch and shopListQuery read and write the same form, and useShopAll() changes it (toggleValue, setRange, setSort, setPage, clear). Scroll position is restored on back.

SEO

  • productMetadata, shopAllMetadata and searchMetadata (from /server) build the title (from the site's seo.titleTemplate), description, canonical URL, robots and Open Graph. The Next.js route helpers call them for you.
  • A listing URL is noindex,follow when it carries two or more filter values, a non-default sort or a search term; its canonical keeps at most one filter value and the page number and drops the sort. Links are always followed. A search page is always noindex; the account page is never indexed.
  • JSON-LD: productJsonLd, breadcrumbJsonLd and itemListJsonLd, emitted by ProductPage and ShopAll (set jsonLd={false} if you render it yourself). Pass baseUrl so links are absolute.
  • A missing product answers 404 and a renamed handle a permanent redirect (308), through the route helpers.

Analytics

The storefront reports the GA4 ecommerce events view_item_list, select_item, view_item, add_to_cart, remove_from_cart, view_cart and begin_checkout to the analytics prop ( { track(event, payload) }). The default reports nothing. gaAnalytics() pushes to dataLayer (Google Tag Manager) or calls gtag; throttleScriptsAnalytics(scripts) sends them through @usethrottle/scripts. Item prices in a payload are decimal amounts made with @usethrottle/money, never minor units.

GA4 through the data layer
// GA4: the storefront reports view_item_list, select_item, view_item, add_to_cart, remove_from_cart,
// view_cart and begin_checkout. Prices in the payloads are decimal amounts (19.99), made with @usethrottle/money.
import { StorefrontProvider, gaAnalytics } from '@usethrottle/storefront-react';
import type { ReactNode } from 'react';

// The page loads gtag.js (or Google Tag Manager) itself. `dataLayer` pushes { event, ecommerce } for GTM;
// 'gtag' calls gtag('event', name, payload) directly.
const analytics = gaAnalytics({ target: 'dataLayer' });

export function Providers({ children }: { children: ReactNode }) {
  return (
    <StorefrontProvider catalogKey="pc_pk_your_browser_key" analytics={analytics}>
      {children}
    </StorefrontProvider>
  );
}

Right to left

dir follows the locale (ar, he, fa and ur are right to left); set it to override. The stylesheet uses logical properties only (inline-start, never left), so layout and scrolling mirror without a second sheet, and the gallery's arrow keys swap sides.

Keyboard and accessibility

  • QuickAdd. A product with several variants opens an options panel; focus moves into it. Tab through its controls. Tab past the last control, Shift+Tab out of the first, or Escape closes the panel and returns focus to the card's button, so the next Tab continues from the card, not from the end of the page (the panel sits at the end of the storefront root, so the browser would otherwise jump there).
  • The cart drawer, quick view and the filter drawer trap focus, close on Escape and return focus to what opened them.
  • The header's search is a combobox: arrow keys move through the suggestions (wrapping), Enter opens the active one or searches, Escape closes the list. The page frame has a skip link to <main> (mainId).
  • The gallery moves between photos with the arrow keys (mirrored in right to left), Home and End; a swipe works on touch.
  • Changing a filter, the sort or the search announces the new result count in a polite live region (not on first load or a page change). A star rating is one image with the label "4.5 out of 5 stars". A swatch is named by its value. The compare button is a toggle with aria-pressed.
  • Heading levels are yours to set where a component is placed in a dialog: BuyBox takes headingLevel.
  • Images always reserve their space (aspectRatio), so nothing jumps while they load; motion respects the reduced-motion setting.

Account page

AccountPage (from /account) shows the signed-in shopper's account, or the sign-in and sign-up forms, through @usethrottle/auth, drawn with the storefront's theme. It needs the account publishable key in the catalog's brand settings (or a Builder's connections, or the throttlePublishableKey prop); without it the page says it is not set up.

The account page
// An account page: the dashboard for a signed-in shopper, sign-in for a signed-out one. It needs
// `@usethrottle/auth` and the account key in your catalog's brand settings (or `throttlePublishableKey`).
import { AccountPage } from '@usethrottle/storefront-react/account';

export function Account() {
  return <AccountPage view="dashboard" onSuccess={() => window.location.assign('/')} />;
}

Next