cimplify

React SDK

Provider-driven React bindings for @cimplify/sdk — data hooks, cart, and three checkout tiers.

curl
npm install @cimplify/sdk
TSX
'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.

TSX
// 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

PropTypeDescription
client?CimplifyClientIf omitted, auto-created from NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY.
childrenReactNodeApp subtree with access to Cimplify context.
onLocationChange?(location: Location) => voidFires when setCurrentLocation is called.

useCimplify()

FieldTypeDescription
clientCimplifyClientSDK client for direct API calls.
businessBusiness | nullBusiness info fetched on mount. Null until loaded.
currencystringBusiness default currency, falls back to "USD".
countrystringBusiness country code, falls back to "US".
locationsLocation[]All business locations.
currentLocationLocation | nullActive location, restored from localStorage on mount.
setCurrentLocation(location: Location) => voidSets active location. Persists to localStorage, survives page refresh.
isReadybooleanTrue after bootstrap (business + locations) completes.
isDemoModebooleanTrue 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

TierComponentControlBest for
1 - Drop-inCimplifyCheckoutMinimalFast launch, SDK handles everything
2 - ControlledElementsProvider + componentsLayoutCustom UX with SDK-managed iframes
3 - HeadlessprocessCheckoutFullCustom payment UI, server-driven flows

Next Steps