The @shopdiddo/checkout-core package is Diddo's embeddable checkout UI for web applications. It ships a fully-styled \<CheckoutPage\> component with a first-class theming API so your checkout experience matches your brand — no redirect required.
📘Before using the SDK, you'll need a Customer Session Token (CST) and a
cart_id. See Customer Session Token (CST) if you haven't minted one yet. Full component and theme type definitions are available in the API Reference.
📦 Installation
Install the package from GitHub Packages:
bashThen import the bundled CSS once at your app entry point (e.g. main.tsx or _app.tsx):
typescript🛒 Using \<CheckoutPage\>
\<CheckoutPage\> is the top-level component. Render it once at a dedicated route — it manages its own internal state.
typescriptProps
| Prop | Type | Default | Description |
|---|---|---|---|
theme | `Theme | PartialTheme` | Default Diddo theme |
environment | `'development' | 'preview' | 'production'` |
apiBaseUrl | string | — | Override the API base URL directly. Takes precedence over environment. |
💬If you need sibling components to access the theme (e.g. a custom header), wrap your app in
\<ThemeProvider\>and omit thethemeprop from\<CheckoutPage\>— it will inherit from the provider above it.
🎨 Theming
Creating a theme
Use createTheme to produce a complete, type-safe theme by merging your overrides onto the Diddo defaults:
typescriptOnly the fields you provide are overridden — everything else falls back to Diddo's defaults. Use defineTheme for the same type inference without merging (useful for building partial theme fragments):
typescriptPassing the theme
Pass directly to \<CheckoutPage\>:
typescriptOr share it across multiple components with \<ThemeProvider\>:
typescriptSetting applyGlobalStyles applies the theme's pageBackground and fontFamily to \<body\>. Leave it off if your app controls its own body styles.
🎛️ Theme Tokens
All theme tokens map to --dc-* CSS variables on the provider wrapper.
colors
| Token | Default | Description |
|---|---|---|
brand | #6366f1 | Primary brand accent — used on interactive controls, links, and the submit button gradient start. |
brandStrong | #4f46e5 | Stronger brand shade — submit button gradient end. |
surface | #ffffff | Card and sheet background color. |
text | #1a1a1a | Default body text. |
textMuted | #64748b | Secondary/muted body text. |
border | rgba(0,0,0,0.1) | Hairline borders. |
accentPrimary | #1a1a1a | Primary text on receipt and overlays. |
accentSecondary | #1a1a1a | Secondary text (labels, headings on receipt). |
accentMuted | #888 | Faded/muted text. |
glassBg | rgba(0,0,0,0.04) | Translucent background behind item images. |
confirmedIconColor | #1a1a1a | Check icon color in the order-confirmed overlay. |
typography
| Token | Default | Description |
|---|---|---|
fontFamily | "Satoshi", system-ui, sans-serif | Full font stack. Set this if you're loading a custom font. |
letterSpacing | normal | Global letter-spacing. |
layout
| Token | Default | Description |
|---|---|---|
containerMaxWidth | 960px | Max width of the main checkout container. |
pageBackground | #f9fafb | Page background (only applied when applyGlobalStyles is set). |
scrollbarWidth | 5px | Custom scrollbar width. |
scrollbarThumb | rgba(0,0,0,0.12) | Scrollbar thumb color. |
scrollbarThumbHover | rgba(0,0,0,0.18) | Scrollbar thumb hover color. |
components
Receipt
| Token | Default |
|---|---|
grandTotalFontSize | 23px |
grandTotalFontWeight | 500 |
totalsRowFontWeight | 500 |
totalsRowOpacity | 0.5 |
orderTotalPaddingTop | 60px |
itemNameWhiteSpace | pre-wrap |
Overlay (order-confirmed screen)
| Token | Default |
|---|---|
titleFontSize | 28px |
iconSize | 80px |
iconBackground | #00000070 |
Card button (payment method buttons)
| Token | Default |
|---|---|
height | auto |
borderRadius | 8px |
outlineColor | rgba(0,0,0,0.1) |
boxShadow | none |
boxShadowHover | none |
boxShadowActive | none |
stripe
Pass a Stripe Appearance object to customise the Stripe-hosted payment iframe. colors.brand is automatically synced to colorPrimary, so the Stripe UI stays in step with your brand color without any extra config:
typescriptanimations
| Value | Behaviour |
|---|---|
'rich' (default) | Full motion — transitions, enter/exit animations. |
'minimal' | Reduced motion. Also forced automatically when the user has prefers-reduced-motion enabled. |
assets
| Token | Description |
|---|---|
logo | Receipt logo — a URL string or bundler-resolved import. |
logoAlt | Alt text for the logo. |