Product Catalog / Storefront components

Theming

A storefront's look comes from several places that can disagree: a Throttle Builder, your own props, your catalog settings and the package's presets. This page says which one wins, field by field, and how to override the result.

Two kinds of setting

  • Catalog display is how the shop works: the listing, the card, the badges, stock text, the product page and its sections, filters, sorts, routes and catalog strings. It is read from your catalog settings. A prop on a component wins over the setting, and the setting over the package default.
  • Site design is how the site looks and speaks: the theme, the brand (store name, logo), the menus, the announcement, SEO defaults, the site strings (footer.copyright, nav.menu, nav.account), the page route and the account key. It is resolved from the sources below.

Site design precedence

The provider resolves the site design once, in resolveSiteDesign (also exported from /server).

FieldsOrder, first source with a value wins
The theme group: preset, tokens, colour scheme1. A Throttle Builder's site design. 2. Your preset, theme and scheme props. 3. The catalog adapter (the catalog settings' own theme). 4. The preset's defaults (clean and auto).
Every other site field: brand, menus, announcement, SEO defaults, site strings, page route1. The Builder. 2. The catalog adapter. 3. The package defaults. Decided field by field.
The account publishable keyThe throttlePublishableKey prop, then the Builder's connections, then none.
Token overridesappearance.variables and appearance.darkVariables, applied last, always. They beat every row above.
  • A null from a source is a value (it clears the field); undefined falls through to the next source.
  • With no Builder, an explicit preset or theme prop means the catalog adapter's theme is skipped: you chose in code, so the catalog's theme does not blend in. The resulting tokens are the preset's, then your theme, then the winning source's values, merged deeply.
  • A Builder whose theme is not customized contributes only its preset and colour scheme.
  • When a Builder's theme shadows a preset, theme or scheme prop, one development warning names the prop. Remove the prop or change it in the Builder.
The catalog adapter is deprecated
Reading site design from the catalog settings (catalogSiteDesign) is a bridge for catalogs that predate the Builder, and it is marked @deprecated. It goes away when the Builder takes over site design. A store that wants to stay independent of it provides its own site design, or sets the theme in code.

Presets

PresetCharacter
cleanThe default; equal to the catalog schema defaults. System fonts, radius 8, comfortable spacing.
editorialPlayfair Display headings over Inter, radius 2, roomy spacing.
boldSpace Grotesk headings over DM Sans, radius 12, comfortable spacing.

Preset tokens (colours for light and dark, fonts, radius, spacing scale) are plain data in @usethrottle/ui/presets (PRESET_NAMES, PRESET_TOKENS). That entry has no React and no directive, so it is safe in a server component, and the Throttle Builder reads the same data. The storefront root carries data-throttle-preset="<name>"; each package keeps its own per-preset CSS for its own components, keyed by that attribute (storefront CSS never reads the tokens from anywhere else).

Pick a preset and adjust it in code
// Pick a preset and adjust tokens in code. For the theme group, a Throttle Builder's design wins over
// these props, and these props win over the catalog's theme. `appearance.variables` always has the last word.
import { StorefrontProvider } from '@usethrottle/storefront-react';
import { PRESET_TOKENS } from '@usethrottle/ui/presets';
import type { ReactNode } from 'react';

export function Providers({ children }: { children: ReactNode }) {
  return (
    <StorefrontProvider
      catalogKey="pc_pk_your_browser_key"
      preset="bold"
      scheme="auto"
      theme={{ radius: 2, spacingScale: 'roomy' }}
      appearance={{ variables: { colorPrimary: '#0b6b3a' } }}
    >
      {children}
    </StorefrontProvider>
  );
}

// The tokens of a preset, for your own CSS: PRESET_TOKENS.clean | .editorial | .bold.
export const boldTokens = PRESET_TOKENS.bold;

Tokens, dark mode and appearance

  • scheme is light, dark or auto (the visitor's system setting). With auto, the dark palette moves into a scoped rule so it beats the stylesheet's own dark rule.
  • theme overrides preset tokens (radius, spacingScale, fonts, and the light and dark palettes).
  • appearance.variables (and darkVariables, used in dark and in auto) set the CSS custom properties directly: colorPrimary, colorBackground, borderRadius, fontFamily and so on. This is the developer's token layer and always has the last word.
  • appearance.parts adds class names per part key, the same as classNames on a component but for the whole tree.
  • Values that carry {, }, ;, url( or @import are dropped from generated CSS, because the CSS can be built from data a site owner typed.

Text and languages

Every string resolves in this order, first match wins: the Builder's strings; your localization prop; for a catalog string, the catalog settings' strings; the package's English (SF_STRINGS_EN, or the SDK's defaults for catalog strings). The catalog adapter's site strings are catalog text and rank with the catalog's. localization is a nested object, for example { cart: { title: 'Basket' } }, so any language is a data change. Strings take {name} placeholders. Set locale (and dir when the locale is not enough) on the provider; prices and dates follow it.

Slot outlets

A SlotOutlet is a place where a host may add content: product.above, product.below, shop.above and shop.below. The storefront core never imports the Throttle Builder; it talks to one through two hooks in @usethrottle/ui: useSiteDesign() (the site design a host provides) and useSlotOutlet(name) (the renderer a host registered for a slot). A product outlet's renderer receives { context } with the product and the chosen variant SKU; a listing outlet's receives the source, the total, the filters, the sort and the page. With no host, or no renderer for a name, the outlet renders nothing, not even its wrapper, so a store without a Builder is unchanged.

SiteDesignProvider and SlotOutletProvider from @usethrottle/ui let a host (or a test) provide them without the Builder package. For the components that take a replacement directly, see Slots.