Every component, prop, hook and theme token in @shopdiddo/react, grouped by what it does.

📘

New to the SDK? Start with the React SDK guide, which walks you from install to a working storefront.

📦 Entry Points

Import only what you use. Your customers then download only what that part of the SDK needs.

🧩 Setting up DiddoProvider

Every Diddo component and hook goes inside a DiddoProvider, which supplies the session token and theme. For a setup example, see step 2 of the React SDK guide.

Checkout, carts and catalogs each add their own provider inside it: CheckoutProvider, CartProvider and ProductsProvider. A Diddo component rendered outside the provider it needs throws an error naming the missing provider.

Props

Session tokens

Mint the CST on your server, never in the browser. Mint it with your customer's email to fill in their details at checkout. See Customer Session Token (CST).

• Changing the token: pass the new value to token. It takes effect straight away, with no reload.
• Signing out: a token can't be cleared. When your customer signs out, remount the provider, for example by changing its key.
• Guest checkout: if your page only checks out a cart you already have the ID for, you can leave token out. Diddo creates a guest session for that checkout itself.
• One token for everything: every CST, including a guest one, works for product catalogs, carts and checkout.

Renewing an expired token

A CST expires after 24 hours. When Diddo rejects it, onAuthError is called: pass a new CST to token. The failed request isn't retried, so your customer may need to repeat their last action.

onAuthError receives the HTTP status and, when available, a requestId for Diddo support. It isn't called when a valid token lacks permission, since a new token wouldn't help.

Loading

The checkout, cart and catalog providers also take a loadingFallback. Use the same component for each, so your customer sees one continuous loading state.

Handling errors

If a Diddo component can't continue, for example because the SDK couldn't load or a cart couldn't be found, DiddoProvider shows errorFallback in its place. The default, ErrorPage, shows a title, a message for your customer, a support code and, when trying again might work, a retry button.

To customize it, pass your own component. It receives error and retry. Only offer retry when error.isRetryable is true. You can wrap ErrorPage rather than start from scratch:

typescript
import { DiddoProvider, ErrorPage, type ErrorFallback } from '@shopdiddo/react';

const CheckoutError: ErrorFallback = ({ error, retry }) => (
  <ErrorPage error={error} onRetry={retry} onGoBack={() => history.back()} />
);

<DiddoProvider token={cst} errorFallback={CheckoutError}>…</DiddoProvider>;

Every Diddo component inside the provider uses the same errorFallback. See Error Handling for error types and support codes.

💬 Toast messages stay visible on top of the error screen, so your customer can still see why something failed.

More than one provider

Each DiddoProvider is completely independent: two on one page don't share a token, a cart, a theme or toast messages.

🏷️ Product catalogs

From @shopdiddo/react/products. Every component goes inside a ProductsProvider, which needs a CST on DiddoProvider. For a catalog page and product page example, see step 3 of the React SDK guide.

ProductsProvider props

query is read once, when the provider mounts. After that, your customer changes it with ProductsFilterPanel, and you can change it with useProducts (see Hooks below). To start again from a new query, for example when your customer navigates to a different team, change the provider's key.

Choosing products

Every field of ProductsQuery is optional.

💬

With gameId, only sort, minPrice, maxPrice, limit and imageWidth apply. Other fields are ignored.

ProductGrid

ProductGrid shows one card per product. While the first page loads it shows placeholder cards. If loading fails it offers a retry, and while there are more products it shows a "Load more" button.

Without onSelectProduct, picking a card opens the product on the same page: a ProductDetail inside the same ProductsProvider shows it. Use this for a drawer or a side panel, and close it with useProductSelection (see Hooks below).

typescript
<ProductGrid
  renderItem={(card, product) => (product.available ? card : <SoldOutBadge>{card}</SoldOutBadge>)}
/>

ProductsFilterPanel

ProductsFilterPanel lets your customer sort and filter the catalog. By default it shows sort, category, color, gender and age options. Pass your own list to replace any of them, or an empty list to hide one.

Without leagues, the league and teams in your query stay fixed. To build the leagues, teams and playerGroups options, use useLeagues and useTeamSummaries (see Hooks below). Each LeagueOption and TeamOption is a { value, label } pair, where value is the slug. To extend a default list rather than replace it, spread the exported default:

typescript
import { ProductsFilterPanel, CATEGORY_OPTIONS } from '@shopdiddo/react/products';

<ProductsFilterPanel categories={[...CATEGORY_OPTIONS, 'Collectibles']} />;

ProductDetail

ProductDetail shows one product: its images, price and options (such as size), a quantity picker and an add-to-cart button. Choose which product it shows in one of three ways:

• productId****: loads the product by its ID. Use this on a product page. If the product no longer exists, your customer sees "This product is no longer available."
• product****: shows a product you already have.
• Neither: shows the product your customer picked in a ProductGrid in the same ProductsProvider. Until they pick one, it shows nothing.

How the add-to-cart button behaves depends on where ProductDetail is:

• Inside a CartProvider****: the button adds the chosen variant and quantity to that cart. This is the usual setup.
• With onAddToCart****: the button calls it instead, for apps that keep their own cart. If it returns a promise that rejects, your customer sees a message asking them to try again.
• Neither: the product is shown read-only, with no quantity picker or button.

To use your own add-to-cart control instead, set showAddToCart={false} and put your control in footer or anywhere else on the page. Read the customer's choice with useProductSelection (see Hooks below).

Building blocks

These are the parts ProductGrid and ProductDetail are made from. Use them to build your own layout inside a ProductsProvider.

Hooks

Use these inside a ProductsProvider to build your own catalog UI.

useProducts(): the catalog for the provider's current query.

To show your own filter count or "Clear filters" button, use activeFilterCount, clearedFilters and shownFilterKeys. Pass shownFilterKeys the same leagues and playerGroups you pass to ProductsFilterPanel, so your count matches the panel's:

typescript
import { useProducts, shownFilterKeys, activeFilterCount, clearedFilters } from '@shopdiddo/react/products';

function ClearFiltersButton({ leagues }: { leagues: LeagueOption[] }) {
  const { query, setQuery } = useProducts();
  const keys = shownFilterKeys({ leagues });
  const count = activeFilterCount(query, keys);

  if (count === 0) return null;
  return <button onClick={() => setQuery(clearedFilters(keys))}>Clear filters ({count})</button>;
}

useProductSelection(): the product your customer is looking at, and their choices.

typescript
import { ProductGrid, ProductDetail, useProductSelection } from '@shopdiddo/react/products';

function CatalogWithDrawer() {
  const { product, selectProduct } = useProductSelection();

  return (
    <>
      <ProductGrid />
      <Drawer open={product !== null} onClose={() => selectProduct(null)}>
        <ProductDetail />
      </Drawer>
    </>
  );
}

useLeagues() and useTeamSummaries(league, teamSlugs): the leagues and teams your customers can filter by.

• useLeagues() returns { leagues, status, error }. Each league has a slug, a name and its teams.
• useTeamSummaries(league, teamSlugs) returns { teams, isPending }. Each team includes its top players, the ones with the most products for sale.

Use them to build ProductsFilterPanel's options:

typescript
import { ProductsFilterPanel, useLeagues, useProducts, useTeamSummaries } from '@shopdiddo/react/products';

function CatalogFilters() {
  const { query } = useProducts();
  const { leagues } = useLeagues();
  const { teams } = useTeamSummaries(query.league, query.teams ?? []);
  const league = leagues.find((option) => option.slug === query.league);

  return (
    <ProductsFilterPanel
      leagues={leagues.map((option) => ({ value: option.slug, label: option.name }))}
      teams={league?.teams.map((team) => ({ value: team.slug, label: team.name })) ?? []}
      playerGroups={teams.map((team) => ({
        team: team.slug,
        label: team.name,
        players: team.players.map((player) => ({ value: player.slug, label: player.displayName })),
      }))}
    />
  );
}

🧺 Carts

From @shopdiddo/react/cart. Every component goes inside a CartProvider. Put it near the top of your app so the cart follows your customer between pages. For a setup example, see step 4 of the React SDK guide.

Diddo creates the cart when your customer first adds something, but doesn't store its ID for you. Save it from onCartIdChange (in local storage, a cookie or your customer's account) and pass it back as cartId.

CartProvider props

cartId is read once, when the provider mounts. To switch to a different cart, change the provider's key.

Adding to the cart

A ProductDetail inside the CartProvider adds to the cart for you (see Product catalogs). To add from anywhere else, such as a featured product on your home page, use AddToCartButton:

typescript
import { AddToCartButton } from '@shopdiddo/react/cart';

<AddToCartButton variantId={variant.id} quantity={1} onAdded={() => openCartDrawer()} />;

The same variant added twice with different customizations becomes two separate lines in the cart, so your customer can change or remove each one on its own.

Showing the cart

CartLineList shows every line in the cart, with a quantity stepper and a remove button on each. CartSummary shows the subtotal, shipping, tax and total.

typescript
import { CartLineList, CartSummary, CartEmptyState } from '@shopdiddo/react/cart';

function CartPage() {
  return (
    <>
      <CartLineList
        emptyState={
          <CartEmptyState message="Find something you love in our store.">
            <Link to="/products">Keep shopping</Link>
          </CartEmptyState>
        }
      />
      <CartSummary />
    </>
  );
}

Changes show straight away. If Diddo can't make a change, for example because there isn't enough stock, the line goes back to how it was and shows why. The stepper never goes above what's in stock or the most your customer can buy in one order.

💬

Shipping and tax depend on where your customer is sending their order. Until they choose a shipping method at checkout, CartSummary shows "Calculated at checkout" for both, and marks the total as an estimate.

Building blocks

CartLineList is made from these. Use them to lay out the cart your own way.

Each takes the ID of a line in the cart. Get the IDs from useCart:

typescript
import { CartLine, useCart } from '@shopdiddo/react/cart';

function CompactCart() {
  const { cart } = useCart();
  return cart?.lines.map((line) => <CartLine key={line.id} lineId={line.id} />);
}

Hooks

Use these inside a CartProvider to build your own cart UI.

useCart(): your customer's cart.

CartAddInput is { variantId, quantity, customizations? }. Quantity changes show straight away and roll back if Diddo refuses them; the returned promise rejects with the reason.

useCartLine(lineId): one line, with line (null once it's removed), isPending, setQuantity(quantity) and remove().

useAddToCart(): for your own add-to-cart buttons. It returns addLine(input), isAdding, error and reset(). Each call to the hook keeps its own isAdding and error, so two buttons on one page each show only their own progress and errors.

🛒 Checkout

From @shopdiddo/react. Use \<CheckoutPage\> for a complete checkout in one component (see step 5 of the React SDK guide), or build your own layout inside a CheckoutProvider.

\<CheckoutPage\> props

cartId and buyer are read once, when the page mounts.

Building your own checkout

Put a CheckoutProvider inside your CartProvider and it checks out your customer's cart. Then add the components you want:

typescript
import {
  CheckoutProvider, BuyerSummary, OrderSummary, PaymentOptions, LegalCopy, PaymentErrorModal, Receipt,
} from '@shopdiddo/react';

function CheckoutRoute() {
  return (
    <CheckoutProvider loadingFallback={<Spinner />}>
      <BuyerSummary />
      <OrderSummary />
      <PaymentOptions onSuccess={() => analytics.track('order_placed')} />
      <LegalCopy sellerTermsUrl="https://example.com/terms" sellerPrivacyUrl="https://example.com/privacy" />
      <PaymentErrorModal />
      <Receipt returnUrl="https://example.com" />
    </CheckoutProvider>
  );
}

You don't need to show or hide anything yourself. Each component knows where the payment is up to: the payment options hide once your customer has paid, and the receipt appears.

💬 Until your customer adds their first item, there's no cart yet, so the checkout shows nothing.

Checking out a cart you created

If you create carts with the Diddo API rather than a CartProvider, pass the cart's ID:

typescript
<CheckoutProvider cartId={cartId} loadingFallback={<Spinner />}>…</CheckoutProvider>

See Working with Carts for creating carts.

CheckoutProvider props

cartId and buyer are read once, when the provider mounts. To check out a different cart, change the provider's key.

Order details

Taking payment

PaymentOptions shows every payment method available to your customer: Apple Pay or Google Pay when their device supports it, and a card form that collects their shipping address and card details.

billingDetails contains the name, email, phone and address your customer paid with, when the payment method provides them. If meta.confirming is true, the payment went through but Diddo hadn't finished confirming the order within a minute. The order is almost certainly placed, and the receipt says so.

Add PaymentErrorModal once inside the CheckoutProvider. It shows your customer what went wrong with a payment, such as a declined card, and lets them try again.

📘

Pay with Visa: contact Diddo to enable Visa payments for your account, then pass visaEnabled. "Pay with Visa" only appears when your customer's CST was minted with their email, and their device supports passkeys.

To lay out payment methods yourself, use the methods PaymentOptions is made from. Each takes onSuccess and onError:

After payment

Receipt appears once the payment is confirmed. It shows your logo, the items, the total and a "Continue Shopping" button.

While the order is being confirmed, OrderStatus shows your customer progress messages that change the longer it takes. Pass stages to use your own messages: each stage is { afterMs, text }, shown from afterMs milliseconds onwards. The defaults are in DEFAULT_ORDER_STATUS_STAGES.

Hooks

useCheckoutStatus(): where the payment is up to, for your own UI, such as hiding your app's navigation while your customer pays.

typescript
import { useCheckoutStatus } from '@shopdiddo/react';

function CheckoutHeader() {
  const { status } = useCheckoutStatus();
  if (status === 'confirming') return <p>Placing your order…</p>;
  return <BackToCartLink />;
}

🎨 Theming

Creating a theme

createTheme merges your changes onto Diddo's defaults. Pass the result to DiddoProvider's theme. For an example, see step 6 of the React SDK guide.

💬 Create your theme once, outside your components. Creating it on every render restyles every Diddo component each time.

To build a theme in parts, use defineTheme. It checks your types without merging anything, so you can combine the parts in createTheme later:

typescript
import { createTheme, defineTheme } from '@shopdiddo/react';

const brandColors = defineTheme({ colors: { brand: '#e63946', brandStrong: '#c1121f' } });
const brandType = defineTheme({ typography: { fontFamily: '"Inter", system-ui, sans-serif' } });

export const myTheme = createTheme({ ...brandColors, ...brandType });

createTheme takes an optional second argument, the theme to build on, which defaults to Diddo's defaultTheme. Use it for variations of your own theme, such as a dark mode:

typescript
export const myDarkTheme = createTheme({ colors: { surface: '#111', text: '#f5f5f5' } }, myTheme);

Sharing the theme with your own components

DiddoProvider's theme covers every Diddo component inside it. If your own components need the theme's values too, wrap them in a ThemeProvider and read the theme with useTheme():

typescript
import { ThemeProvider, useTheme } from '@shopdiddo/react';

function CheckoutHeader() {
  const theme = useTheme();
  return <img src={theme.assets.logo} alt={theme.assets.logoAlt} />;
}

<ThemeProvider theme={myTheme}>
  <DiddoProvider token={cst}>
    <CheckoutHeader />
    …
  </DiddoProvider>
</ThemeProvider>;

⚠️

Put any ThemeProvider outside your CheckoutProvider, never between it and the payment components. The card fields take their styling from the theme around the CheckoutProvider, so a different theme inside it splits the payment form across two styles.

Colors

Typography

The SDK's stylesheet includes the Satoshi font. To use your own font, load it in your app as usual, then set fontFamily.

Layout

Animations

animations is 'rich' (the default) or 'minimal'. 'rich' adds the animated order-confirmed screen and the receipt's entrance; 'minimal' shows still versions. If your customer has asked their device to reduce motion, Diddo always uses 'minimal'. Your own components can follow the same rule with useAnimationMode(), which returns the mode Diddo is actually using.

Assets

Component tokens

To change one part of one component, set its tokens under components, grouped by area:

typescript
const myTheme = createTheme({
  components: {
    checkout: { submit: { background: '#e63946' } },
    products: { card: { radius: '4px' }, pill: { selectedBackground: '#e63946' } },
    cart: { summary: { border: 'none' } },
  },
});

Every token takes a CSS value. To see the defaults, log defaultTheme.components.

💬

Dark themes: besides the colors, set components.checkout.sheet.shadow and components.checkout.receipt.shadow to 'none'. The default shadows are designed for light backgrounds.

Card and wallet payments

The card fields and the Apple Pay and Google Pay buttons are drawn by Stripe, so they're styled through components.checkout.stripe. appearance follows Stripe's Appearance API, except for variables Stripe has deprecated. Its colorPrimary follows your colors.brand unless you set it.

typescript
const myTheme = createTheme({
  components: {
    checkout: {
      stripe: {
        appearance: {
          variables: { borderRadius: '4px', fontSizeBase: '15px', iconColor: '#555' },
        },
        expressCheckout: {
          buttonHeight: 48,
          buttonTheme: { applePay: 'black', googlePay: 'black' },
        },
      },
    },
  },
});

Matching your own components

To make your own components match a Diddo theme, use these CSS variables inside any Diddo provider. Their values come from the active theme.

css
.my-banner {
  background: var(--dc-brand);
  color: var(--dc-on-brand);
  font-family: var(--dc-font-family);
}

Only rely on the variables in this table. Diddo's components use others, but those can change in any release.

👈 Back to the React SDK guide