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.
"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}`)}
/>
);
}| Prop | Type | Description |
|---|---|---|
template | CatalogueTemplate | "default" | "compact" |
products | Product[] | Pre-fetched for SSR; skips client fetch. |
categories | Category[] | Pre-fetched for SSR. |
facets | PropertyFacet[] | Sidebar filters. |
pageSize | number | Default 24. |
onProductClick | (p: Product) => void | Card click handler. |
renderCard | (p) => ReactNode | Replace 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.
"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} />}
/>
);
}| Prop | Type | Description |
|---|---|---|
productId | string | Slug or `prod_` ID. Skipped when `product` is supplied. |
product | ProductWithDetails | Pre-fetched for SSR. |
pages | Record<slug, Component> | Per-slug layout overrides. |
templates | Record<key, Component> | Per-product-type layout overrides. |
onAddToCart | (p, qty, opts) => void | Override default cart behavior. |
relatedProducts | Product[] | Pre-fetched related list. |
showRelated | boolean | Default true. |
CartPage
Full cart route with line-item editing, discount input, and a checkout CTA.
"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"
/>
);
}| Prop | Type | Description |
|---|---|---|
template | "default" | "compact" | Layout variant. |
onCheckout | () => void | Required to navigate to /checkout. |
onContinueShopping | () => void | "Continue shopping" handler. |
onDiscountApply | (v: DiscountValidation) => void | Fires after server validates a code. |
onDiscountClear | () => void | |
showDiscount | boolean | Show the coupon input. |
checkoutLabel | string | Button 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.
"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)}
/>
);
}| Prop | Type | Description |
|---|---|---|
title | string | Page heading. |
onComplete | (r: ProcessCheckoutResult) => void | Required success handler. |
onError | (e: { code, message }) => void | Failure 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.
"use client";
import { CimplifyAccount } from "@cimplify/sdk/react";
export default function AccountOrders() {
return <CimplifyAccount section="orders" />;
}| Prop | Type | Description |
|---|---|---|
section | "dashboard" | "orders" | "addresses" | "payment-methods" | "sessions" | "settings" | Initial view. |
appearance | { theme, variables } | Light / dark + brand color, font, radius. |
onLogout | () => void | Fired 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")}
/>| Prop | Type | Description |
|---|---|---|
onCheckout | () => void | Drawer auto-closes first. |
onContinueShopping | () => void | Defaults to close. |
onShop | () => void | Empty-state CTA. |
title | string | Heading. |
freeShippingThreshold | number | In 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="+" />| Prop | Type | Description |
|---|---|---|
amount | number | string | Required. |
currency | CurrencyCode | Skips provider lookup. |
prefix | string | Rendered before the formatted amount. |
className | string |
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
| Group | Components |
|---|---|
| Pages | CataloguePage, ProductPage, CartPage, CheckoutPage, SearchPage, CollectionPage, OrderDetailPage, OrderHistoryPage, DealsPage, BookingsPage, BookingPage, CimplifyAccount |
| Cart drawer | CartDrawerProvider, CartDrawer, CartSummary |
| Cards | FoodProductCard, RetailProductCard, WholesaleProductCard, DigitalProductCard, BundleProductCard, CompositeProductCard, StandardServiceCard, CompactServiceCard, ScheduleServiceCard, RentalServiceCard, AccommodationCard, LeaseServiceCard, SubscriptionCard, ProductCard |
| Customizers | ProductCustomizer, VariantSelector, AddOnSelector, BundleSelector, CompositeSelector, BillingPlanSelector, CustomerInputFields |
| Grids & filters | ProductGrid, CategoryGrid, CategoryFilter, SearchInput, StoreNav, RecentlyViewed, RecommendationCarousel |
| Scheduling | SlotPicker, DateSlotPicker, StaffPicker, ResourcePicker, BookingCard, BookingList, AvailabilityBadge |
| Primitives | Price, PriceRange, QuantitySelector, DealBanner, SaleBadge, DiscountInput, DeliveryEstimate, VolumePricing, LocationPicker, CurrencySelector, SessionMessageBanner, ProductImageGallery, ProductSheet, OrderSummary, OrderHistory, ChatWidget |
Where next
-
Hooks reference Drive components from data hooks.
-
Eject a component
cimplify add <name>.