React SDK
Provider-driven React bindings for @cimplify/sdk — data hooks, cart, and three checkout tiers.
npm install @cimplify/sdk'use client';
import { CimplifyProvider, useCimplify, useProducts, useCart } from '@cimplify/sdk/react';
export default function App() {
return (
<CimplifyProvider>
<Shop />
</CimplifyProvider>
);
}
function Shop() {
const { business, currency, isReady, isDemoMode } = useCimplify();
const { products, isLoading } = useProducts({ limit: 12 });
const { addItem, itemCount } = useCart();
if (!isReady || isLoading) return <p>Loading...</p>;
return (
<div>
<h1>{business?.name} ({currency})</h1>
{isDemoMode && <span>Demo Mode</span>}
<p>Cart: {itemCount} items</p>
{products.map((p) => (
<button key={p.id} onClick={() => addItem(p)}>
{p.name}
</button>
))}
</div>
);
}CimplifyProvider
Bootstraps business info and locations on mount, persists selected location in localStorage, and exposes the SDK client to all descendants.
// With explicit client
import { createCimplifyClient } from '@cimplify/sdk';
const client = createCimplifyClient({ publicKey: 'pk_test_...' });
<CimplifyProvider client={client}>
{children}
</CimplifyProvider>
// Without client — auto-creates from NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY
<CimplifyProvider>
{children}
</CimplifyProvider>Props
| Prop | Type | Description |
|---|---|---|
client? | CimplifyClient | If omitted, auto-created from NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY. |
children | ReactNode | App subtree with access to Cimplify context. |
onLocationChange? | (location: Location) => void | Fires when setCurrentLocation is called. |
useCimplify()
| Field | Type | Description |
|---|---|---|
client | CimplifyClient | SDK client for direct API calls. |
business | Business | null | Business info fetched on mount. Null until loaded. |
currency | string | Business default currency, falls back to "USD". |
country | string | Business country code, falls back to "US". |
locations | Location[] | All business locations. |
currentLocation | Location | null | Active location, restored from localStorage on mount. |
setCurrentLocation | (location: Location) => void | Sets active location. Persists to localStorage, survives page refresh. |
isReady | boolean | True after bootstrap (business + locations) completes. |
isDemoMode | boolean | True when public key is empty. No API calls, all data null. |
Bootstrap Sequence
On mount, the provider fetches business info and locations in parallel, resolves the initial location from localStorage (or falls back to the first location), then sets isReady=true. Changing location with setCurrentLocation writes to localStorage and invalidates all data hook caches since prices are location-dependent.
Demo Mode
When publicKey is empty or not set, the provider enters demo mode: isDemoMode=true, no API calls are made, and business, locations, and currentLocation remain null. Useful for development and prototyping without a backend.
Checkout Tiers
| Tier | Component | Control | Best for |
|---|---|---|---|
| 1 - Drop-in | CimplifyCheckout | Minimal | Fast launch, SDK handles everything |
| 2 - Controlled | ElementsProvider + components | Layout | Custom UX with SDK-managed iframes |
| 3 - Headless | processCheckout | Full | Custom payment UI, server-driven flows |