cimplify
TypeScript SDKReact

Component catalog

90+ React components ship in `@cimplify/sdk/react`. This page covers the page components you mount on routes, the cart drawer, and the most-used primitives. Every component is also [ejectable](/docs/cli/components) via ` cimplify add <name>` when you need full control.

All components must descend from a <CimplifyProvider>. Components that use the cart drawer additionally need <CartDrawerProvider> in scope. See the React overview.

Page components

CataloguePage

Filterable, paginated grid for the shop index. Templates: default, compact. Pre-fetch products and facets server-side and pass them as props to skip the loading state.

app/shop/page.tsx
"use client";
import { CataloguePage } from "@cimplify/sdk/react";
import { useRouter } from "next/navigation";

export default function Shop() {
  const router = useRouter();
  return (
    <CataloguePage
      pageSize={24}
      defaultSort={{ by: "popularity", order: "desc" }}
      onProductClick={(p) => router.push(`/products/${p.slug ?? p.id}`)}
    />
  );
}
PropTypeDescription
templateCatalogueTemplate"default" | "compact"
productsProduct[]Pre-fetched for SSR; skips client fetch.
categoriesCategory[]Pre-fetched for SSR.
facetsPropertyFacet[]Sidebar filters.
pageSizenumberDefault 24.
onProductClick(p: Product) => voidCard click handler.
renderCard(p) => ReactNodeReplace the card entirely.

ProductPage

Full PDP with <ProductCustomizer>, gallery, related products, and JSON-LD. Auto-picks the right layout for the product type (food, retail, wholesale, service, digital, bundle, composite). Override per-slug or per-template.

app/products/[slug]/page.tsx
"use client";
import { ProductPage } from "@cimplify/sdk/react";
import { useParams } from "next/navigation";
import Image from "next/image";

export default function Product() {
  const { slug } = useParams<{ slug: string }>();
  return (
    <ProductPage
      productId={slug}
      renderImage={(p) => <Image {...p} width={1200} height={1200} />}
    />
  );
}
PropTypeDescription
productIdstringSlug or `prod_` ID. Skipped when `product` is supplied.
productProductWithDetailsPre-fetched for SSR.
pagesRecord<slug, Component>Per-slug layout overrides.
templatesRecord<key, Component>Per-product-type layout overrides.
onAddToCart(p, qty, opts) => voidOverride default cart behavior.
relatedProductsProduct[]Pre-fetched related list.
showRelatedbooleanDefault true.

CartPage

Full cart route with line-item editing, discount input, and a checkout CTA.

app/cart/page.tsx
"use client";
import { CartPage } from "@cimplify/sdk/react";
import { useRouter } from "next/navigation";

export default function Cart() {
  const router = useRouter();
  return (
    <CartPage
      onCheckout={() => router.push("/checkout")}
      onContinueShopping={() => router.push("/shop")}
      showDiscount
      checkoutLabel="Proceed to checkout"
    />
  );
}
PropTypeDescription
template"default" | "compact"Layout variant.
onCheckout() => voidRequired to navigate to /checkout.
onContinueShopping() => void"Continue shopping" handler.
onDiscountApply(v: DiscountValidation) => voidFires after server validates a code.
onDiscountClear() => void
showDiscountbooleanShow the coupon input.
checkoutLabelstringButton text.

CheckoutPage

Single-component checkout. Reads the cart and the active customer session, collects contact / address / payment, and emits a flat CheckoutFormData to the API. On success it returns a ProcessCheckoutResult with the new order.

app/checkout/page.tsx
"use client";
import { CheckoutPage } from "@cimplify/sdk/react";
import { useRouter } from "next/navigation";

export default function Checkout() {
  const router = useRouter();
  return (
    <CheckoutPage
      title="Checkout"
      onComplete={(r) => router.push(`/orders/${r.order?.id}`)}
      onError={(e) => console.error(e.code, e.message)}
    />
  );
}
PropTypeDescription
titlestringPage heading.
onComplete(r: ProcessCheckoutResult) => voidRequired success handler.
onError(e: { code, message }) => voidFailure handler.

SearchPage

Search results route with sidebar facets. Reads the query from your router; you wire it through searchOptions.

<SearchPage
  placeholder="Search products"
  searchOptions={{ query: q, limit: 24 }}
  onQuickAdd={(p) => addItem(p)}
/>

CimplifyAccount

Hosted account portal (orders, addresses, payment methods, sessions, settings) rendered in a Cimplify-managed iframe. Accept a section prop to deep-link.

app/account/orders/page.tsx
"use client";
import { CimplifyAccount } from "@cimplify/sdk/react";

export default function AccountOrders() {
  return <CimplifyAccount section="orders" />;
}
PropTypeDescription
section"dashboard" | "orders" | "addresses" | "payment-methods" | "sessions" | "settings"Initial view.
appearance{ theme, variables }Light / dark + brand color, font, radius.
onLogout() => voidFired on sign-out.

Cart drawer

CartDrawerProvider

Owns the drawer's open / closed state for the whole app. Defaults to opening the drawer when an item is added to the cart.

<CartDrawerProvider openOnAdd>
  {children}
</CartDrawerProvider>

CartDrawer

The slide-over panel. Mount it once near the root, control via useCartDrawer().

<CartDrawer
  title="Your cart"
  freeShippingThreshold={500}
  onCheckout={() => router.push("/checkout")}
  onContinueShopping={() => close()}
  onShop={() => router.push("/shop")}
/>
PropTypeDescription
onCheckout() => voidDrawer auto-closes first.
onContinueShopping() => voidDefaults to close.
onShop() => voidEmpty-state CTA.
titlestringHeading.
freeShippingThresholdnumberIn business currency. 0 disables the progress bar.

Primitives

Price

Renders a money amount in the active business currency. Accepts strings (the on-the-wire Money type) or numbers. Use parsePrice() when you need numeric math.

import { Price } from "@cimplify/sdk/react";

<Price amount={product.price} />            // uses provider currency
<Price amount="29.99" currency="USD" />     // explicit
<Price amount={item.adjustment} prefix="+" />
PropTypeDescription
amountnumber | stringRequired.
currencyCurrencyCodeSkips provider lookup.
prefixstringRendered before the formatted amount.
classNamestring

QuantitySelector

const [qty, setQty] = useState(1);

<QuantitySelector
  value={qty}
  onChange={setQty}
  min={1}
  max={10}
/>

DealBanner

Auto-loads active deals via useDeals unless you pass deals.

<DealBanner
  limit={3}
  onDealClick={(d) => router.push(`/deals/${d.slug}`)}
/>

DeliveryEstimate

Calculates a delivery fee for a drop-off location. Surfaces it inline on a PDP or in the cart.

<DeliveryEstimate
  latitude={5.55}
  longitude={-0.196}
  country="GH"
  onFeeCalculated={(f) => setShippingFee(f.amount)}
/>

ChatWidget

Floating bubble + panel for the merchant's support chat. Polls every pollInterval ms (default 3000) for new messages.

<ChatWidget
  businessName="Akua's Bakery"
  greeting="Hi! How can we help?"
  starters={[
    { id: "delivery", label: "Where's my order?" },
    { id: "hours", label: "What are your hours?" },
  ]}
  position="bottom-right"
/>

Full export reference

GroupComponents
PagesCataloguePage, ProductPage, CartPage, CheckoutPage, SearchPage, CollectionPage, OrderDetailPage, OrderHistoryPage, DealsPage, BookingsPage, BookingPage, CimplifyAccount
Cart drawerCartDrawerProvider, CartDrawer, CartSummary
CardsFoodProductCard, RetailProductCard, WholesaleProductCard, DigitalProductCard, BundleProductCard, CompositeProductCard, StandardServiceCard, CompactServiceCard, ScheduleServiceCard, RentalServiceCard, AccommodationCard, LeaseServiceCard, SubscriptionCard, ProductCard
CustomizersProductCustomizer, VariantSelector, AddOnSelector, BundleSelector, CompositeSelector, BillingPlanSelector, CustomerInputFields
Grids & filtersProductGrid, CategoryGrid, CategoryFilter, SearchInput, StoreNav, RecentlyViewed, RecommendationCarousel
SchedulingSlotPicker, DateSlotPicker, StaffPicker, ResourcePicker, BookingCard, BookingList, AvailabilityBadge
PrimitivesPrice, PriceRange, QuantitySelector, DealBanner, SaleBadge, DiscountInput, DeliveryEstimate, VolumePricing, LocationPicker, CurrencySelector, SessionMessageBanner, ProductImageGallery, ProductSheet, OrderSummary, OrderHistory, ChatWidget

Where next

On this page