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
StorefrontProviderand 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
# 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.
| Entry | What it holds |
|---|---|
@usethrottle/storefront-react | The components and hooks (client). |
@usethrottle/storefront-react/server | Loaders, metadata and JSON-LD builders, the server catalog client. No React. |
@usethrottle/storefront-react/next | Next.js route helpers and the signed revalidate and sync handlers. Server only. |
@usethrottle/storefront-react/next/client | StorefrontNextProvider, the provider wired to Next's router and links. |
@usethrottle/storefront-react/account | AccountPage. Needs @usethrottle/auth. |
@usethrottle/storefront-react/styles.css | The 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.
| Key | Variable | Used by |
|---|---|---|
| Browser key | NEXT_PUBLIC_THROTTLE_CATALOG_KEY | The 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 key | THROTTLE_CATALOG_SERVER_KEY | Your 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
# 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_...
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 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.
| Prop | Meaning |
|---|---|
catalogKey | The browser key. Give this or client. |
client | A ready catalog client (a server-built one, or a fixture in tests). |
settings | The settings answered on the server (loadSettings). The first render uses them with no request. |
preset, theme, scheme | The look. See Theming. |
locale, currency, dir | Language and currency for the reads. dir defaults from the locale (right to left for Arabic, Hebrew and the like). |
appearance | parts (class names per part), variables and darkVariables (token overrides, the last word). |
localization | Text overrides for any string, in any language. |
analytics | Where GA4-shaped events go. See Analytics. |
router, linkComponent | How the URL is read and links are drawn. StorefrontNextProvider sets both. |
customerKey, customerCart, cartStorage, cartUrls | Cart wiring. See One cart. |
generationWatch | The open tab's check for a catalog change. Default on, every 60 s at the least; false turns it off. |
injectStyles | Default 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. |
imageOrigin | Where 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.customerKeyandcustomerCart: whose cart this is, and resuming a signed-in customer's cart on any device.cartUrls:returnUrl,cancelUrlandstorefrontUrl, sent on every cart and used bycheckout(). Each is an absolute https URL on an allowed return website.throttleBaseUrlandthrottleCheckoutUrl: Throttle's API and hosted pages, when they are not the defaults.
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
| Area | Order, 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 overrides | appearance.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. |
| Text | The 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:
@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.cssstarts 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,componentsandutilitiesare declared empty, so the order is the same and your unlayered CSS still wins overthrottle.
/* 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';
// 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,shopAllMetadataandsearchMetadata(from/server) build the title (from the site'sseo.titleTemplate), description, canonical URL, robots and Open Graph. The Next.js route helpers call them for you. -
A listing URL is
noindex,followwhen 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 alwaysnoindex; the account page is never indexed. -
JSON-LD:
productJsonLd,breadcrumbJsonLdanditemListJsonLd, emitted byProductPageandShopAll(setjsonLd={false}if you render it yourself). PassbaseUrlso 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: 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:
BuyBoxtakesheadingLevel. -
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.
// 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
- Components: every component and hook, by area.
- Theming: precedence, presets, tokens, slots.
- Next.js and caching: route helpers and the hosting-cost rules.
- Recipes: restyle, swap a slot, headless filters, GA4, Vite and more.
- create-store: scaffold a store.