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).
| Fields | Order, first source with a value wins |
|---|---|
| The theme group: preset, tokens, colour scheme | 1. 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 route | 1. The Builder. 2. The catalog adapter. 3. The package defaults. Decided field by field. |
| The account publishable key | The throttlePublishableKey prop, then the Builder's connections, then none. |
| Token overrides | appearance.variables and appearance.darkVariables, applied last, always. They beat every row above. |
- A
nullfrom a source is a value (it clears the field);undefinedfalls through to the next source. -
With no Builder, an explicit
presetorthemeprop 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 yourtheme, 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,themeorschemeprop, one development warning names the prop. Remove the prop or change it in the Builder.
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
| Preset | Character |
|---|---|
clean | The default; equal to the catalog schema defaults. System fonts, radius 8, comfortable spacing. |
editorial | Playfair Display headings over Inter, radius 2, roomy spacing. |
bold | Space 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 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
-
schemeislight,darkorauto(the visitor's system setting). Withauto, the dark palette moves into a scoped rule so it beats the stylesheet's own dark rule. -
themeoverrides preset tokens (radius,spacingScale,fonts, and the light and dark palettes). -
appearance.variables(anddarkVariables, used in dark and inauto) set the CSS custom properties directly:colorPrimary,colorBackground,borderRadius,fontFamilyand so on. This is the developer's token layer and always has the last word. -
appearance.partsadds class names per part key, the same asclassNameson a component but for the whole tree. -
Values that carry
{,},;,url(or@importare 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.