Theme SDK

Creating a Theme

Use createTheme to define a storefront theme:

import {
  createTheme, TImage, THeading,
  TParagraph, TColor, TSection
} from "threeu-sdk/theme";

function HomePage() {
  return (
    <TSection name="home.hero">
      <TImage name="home.hero.image" src="/hero.jpg" alt="Hero" />
      <THeading name="home.hero.title">
        Welcome to our store
      </THeading>
      <TParagraph name="home.hero.subtitle">
        Discover our latest collection.
      </TParagraph>
      <button style={{
        backgroundColor: TColor("home.hero.buttonColor", "#000")
      }}>
        Shop now
      </button>
    </TSection>
  );
}

export default createTheme({
  name: "Modern Luxury",
  slug: "modern-luxury",
  visibility: "public",
  pages: { home: HomePage }
});

Public vs Exclusive

Public themes are listed on the ThreeU marketplace. Any merchant can install and customize them.

Exclusive themes are private to a specific brand. Built under contract for a single merchant.

The name Prop

Every editable component uses the name prop as its customization key:

• home.hero.title — Title in the hero section of home page
• product.gallery.mainImage — Main image in product gallery
• footer.newsletter.heading — Heading in footer newsletter

Merchants edit these values through the ThreeU admin panel without touching code.

Three Classes of Component

The Theme SDK is headless-first — hooks are the real API and components are optional. Components come in three classes:

• Editable primitives register merchant-editable fields for the visual editor: TText, THeading, TParagraph, TSpan, TImage, TLink, TButton, TColor, TSection.
• Functional primitives solve platform concerns without dictating layout: TPrice, TMoney, TLocalizedText, TJsonLd, and TAddress (captures { lat, lng, address }).
• Recipes are optional convenience components you can always replace with hooks: TProductCard, TProductGrid, TCollectionGrid, TCartSummary, TCheckoutForm.

Rule: no connected component is ever the required way to access a capability — everything a recipe does is reachable through the hooks.

Data & Commerce Hooks

Wrap your theme in <ThreeuThemeProvider> and the hooks read live brand data:

• Catalog: useProducts(), useProduct({ id \| slug }) (headless controller with options/variant/quantity), useCollections()
• Cart: useCart(), useAddToCart(productState) — adapter-based, storage-agnostic
• Buy-flow: useDeliveryMethods(), useDeliveryQuote(), usePaymentMethods(), useCoupon(), useCheckout(), useAddress()
• Analytics: useTracker() → pixels (Meta/TikTok/Snap/Google) + ThreeU
• Context: useBrand(), useLocale(), useCurrency(), useTheme()

Full walkthroughs live in Storefront Themes → Commerce & Checkout and Headless (Advanced). Normalized domain models (StorefrontProduct, …) come from threeu-sdk/domain; the cart adapter from threeu-sdk/cart; the tracker from threeu-sdk/analytics.