The @shopdiddo/react package is Diddo's SDK for React web apps. It gives you ready-made, themeable components for product catalogs, carts and checkout, so your customers can browse, shop and pay without leaving your app.

This guide takes you from install to a working storefront in seven steps. For every prop, hook and theme token, see the React SDK Reference.

📘

Before you start, you'll need a Diddo API key and a way to mint a Customer Session Token (CST) on your server. See Customer Session Token (CST).

📱

Building a native iOS or Android app? Load Diddo's hosted checkout in a WebView instead. See Hosted Checkout Flow.

This section covers:

1. Installing the SDK
2. Connecting it to Diddo with DiddoProvider
3. Showing a product catalog
4. Adding a cart
5. Adding checkout
6. Matching your brand
7. Allowing Diddo in your Content Security Policy

📦 1. Install the SDK

Requirements

• React 19 and react-dom 19
• An ESM-aware bundler, such as Vite, webpack 5 or Next.js (including the App Router)

The SDK comes with everything else it needs, including Stripe.

bash
npm install @shopdiddo/react
# or
yarn add @shopdiddo/react
# or
pnpm add @shopdiddo/react

Import the stylesheet once at your app's entry point, for example main.tsx or _app.tsx:

typescript
import '@shopdiddo/react/styles.css';

The SDK has three entry points. Import only what you use, so your customers download only what they need.

🧩 2. Add DiddoProvider

Every Diddo component goes inside a DiddoProvider. It connects the SDK to Diddo with your customer's session token and applies your theme. Render one high in your tree:

typescript
import { DiddoProvider } from '@shopdiddo/react';
import '@shopdiddo/react/styles.css';

export function App({ cst }: { cst: string }) {
  return (
    <DiddoProvider token={cst} loadingFallback={<Spinner />}>
      <Routes />
    </DiddoProvider>
  );
}

Getting the token

Mint the CST on your server and pass it to the page. Never put your Diddo API key in the browser. Mint it with your customer's email whenever you know who they are, so their details are filled in for them at checkout.

Renewing the token

A CST expires after 24 hours. When that happens, onAuthError is called: mint a new CST and pass it to token. It takes effect straight away, with no reload.

typescript
const [cst, setCst] = useState(initialCst);

<DiddoProvider
  token={cst}
  onAuthError={async () => setCst(await fetch('/api/diddo-session').then((res) => res.text()))}
>
  …
</DiddoProvider>;

When your customer signs out, remount the provider, for example by changing its key.

🏷️ 3. Show a product catalog

Catalog components come from @shopdiddo/react/products and go inside a ProductsProvider. A typical setup has a catalog page and a product page:

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

function CatalogPage() {
  const navigate = useNavigate();

  return (
    <ProductsProvider query={{ league: 'nba', teams: ['lakers'] }} loadingFallback={<Spinner />}>
      <ProductsFilterPanel />
      <ProductGrid onSelectProduct={(product) => navigate(`/products/${product.id}`)} />
    </ProductsProvider>
  );
}

function ProductPage({ productId }: { productId: string }) {
  return (
    <ProductsProvider loadCatalog={false} loadingFallback={<Spinner />}>
      <ProductDetail productId={productId} />
    </ProductsProvider>
  );
}

• query chooses the products to show, using the same filters as the Products API: league, teams, players, category, price and more.
• ProductsFilterPanel lets your customer sort and filter.
• ProductDetail shows images, options such as size, and an add-to-cart button. Inside a CartProvider (next step), that button adds to your customer's cart.

💡

To open products in a drawer instead of a new page, or to build your own catalog UI with hooks, see Product catalogs in the React SDK Reference.

🧺 4. Add a cart

Put a CartProvider near the top of your app so the same cart follows your customer from page to page. Diddo creates the cart when they first add something. Save its ID so they can pick up where they left off:

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

const CART_KEY = 'diddo_cart_id';

function saveCartId(cartId: string | null) {
  if (cartId) localStorage.setItem(CART_KEY, cartId);
  else localStorage.removeItem(CART_KEY);
}

<DiddoProvider token={cst}>
  <CartProvider cartId={localStorage.getItem(CART_KEY)} onCartIdChange={saveCartId}>
    <Routes />
  </CartProvider>
</DiddoProvider>;

Then add a cart page:

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

function CartPage() {
  return (
    <>
      <CartLineList />
      <CartSummary />
    </>
  );
}

CartLineList shows each item with a quantity stepper and a remove button. CartSummary shows the totals. To add to the cart 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} />;

🛒 5. Add checkout

\<CheckoutPage\> is a complete checkout in one component: payment options, payment errors, an order-confirmed screen and the receipt. Inside your CartProvider, it checks out your customer's cart:

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

function CheckoutRoute() {
  return <CheckoutPage returnUrl="https://example.com" header={<img src="/logo.svg" alt="My Brand" />} />;
}

Your customer can pay with Apple Pay or Google Pay when their device supports it, or by card. To offer Pay with Visa, contact Diddo to enable it for your account.

💡

To check out a cart you created with the Diddo API, or to build your own checkout layout from individual components, see Checkout in the React SDK Reference.

🎨 6. Match your brand

Every Diddo component is styled by one theme. Set only what you want to change; everything else keeps Diddo's defaults:

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

export const myTheme = createTheme({
  colors: { brand: '#e63946', brandStrong: '#c1121f', onBrand: '#ffffff' },
  typography: { fontFamily: '"Inter", system-ui, sans-serif' },
  assets: { logo: '/images/my-brand-logo.svg', logoAlt: 'My Brand' },
});

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

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

For every color, font, layout and component token, and for styling the card and wallet buttons, see Theming in the React SDK Reference.

🛡️ 7. Allow Diddo in your Content Security Policy

If your site sends a Content Security Policy, allow these sources:

If Visa payments are enabled for your account, also add https://vts.auth.visa.com to frame-src. On localhost, Visa uses its test environment, so allow https://sbx.vts.auth.visa.com in development too.

If one of these sources is blocked, DiddoProvider shows its error screen instead of loading forever.

⚠️ Handling Errors

If a Diddo component can't continue, for example because a cart couldn't be found, DiddoProvider shows an error screen in its place, with a support code and, when trying again might work, a retry button. To use your own screen, pass errorFallback. See Handling errors in the React SDK Reference, and Error Handling for error types.

🧪 Testing Your Integration

In your tests, mock Diddo's API at the network layer (for example with MSW) rather than mocking the SDK's modules.

📡 Data the SDK Sends to Diddo

• Version information. Each request includes the SDK version, so Diddo can support the versions in use.
• Error reports. When something goes wrong in the SDK, it sends an error report to Diddo. It doesn't use or change your own error tracking, doesn't record your customers' clicks, console output or navigation, doesn't send personal data, and removes card details from every report.

👉 Next: React SDK Reference →