` holding the frame), the SEO components (head tags), and the consent banner's default dialog and `` (which render only when you give them no content of your own). ## Providers and context ### ShopkitProvider ```tsx theme={null} {children} {children} ``` Makes one client and one shared [`CartStore`](/kit/reference/cart) available to the tree. Both are created once and kept for the provider's lifetime. By default it also mounts cookie consent, the default banner and the shop's own analytics, gated on the shopper's decision (see the `consent` prop). A plain config object, which can cross a server-to-client boundary. Read once, not a render dependency. See [Client](/kit/reference/client). A client you built yourself. Takes precedence over `config`. A cart read on the server. The store starts `ready`, so SSR and the first client paint agree. Sell the whole tree into one campaign storefront. Changing it rebuilds the client and the cart store. With a prebuilt `client`, it must match that client's binding or it throws. Shorthand for `config.currency`: the currency to browse in until the shopper picks one, so a **default**, not an override. A later change switches the same client with `setCurrency()` without rebuilding it: catalog hooks refetch and the same cart is re-read. A change to `null` returns to the value the provider **mounted** with, not necessarily the shop's own currency; mount with no `currency` if `null` should mean the shop's own. With a prebuilt `client` the mount-time value is ignored (give the client its `currency`) and only later changes are forwarded. See [Currencies](/kit/concepts/currencies). Shapes the cookie consent and analytics the provider mounts, which are **on by default**. It does not switch them off: the one switch is `consent: false` in the client `config`, which a server client's checkout handoff reads too. `consent={false}` on the prop still turns consent off for this tree, but is **deprecated** and warns, because a server-started checkout cannot see it. The decision as the server read it (`await shopkit.consent.read()`), so the first paint shows the right banner state with no flash. Without it the banner waits for hydration. Language of the built-in copy (`en`, `sv`, `da`, `nb`, `fi`), for the banner and every `` below. Set it when rendering on the server. Adds a "Privacy policy" link to the banner. Overrides for any of the banner's built-in strings. `false` renders no banner (render your own with `` or `useConsent()`); a function is rendered in the default banner's place. Leave out the default banner's stylesheet. Extra class on the default banner's root. `false` keeps the banner and loads no pixel; an object takes the `` options (extra `destinations`, `auto: false`, `requireConsent`, `loadBeforeConsent`, …). A store you built yourself; the store options are then ignored. The consent store's options. Prefer setting `revision` and `cookieName` once in `config.consent`, where the server read and the checkout handoff see them too. A provider nested inside another (a campaign provider inside the site's) reuses the outer consent store, banner and analytics hub. See [Consent and analytics](/kit/concepts/consent-and-analytics). ### useShopkit / useShopkitContext ```ts theme={null} useShopkit(): ShopkitClient useShopkitContext(): { client: ShopkitClient; cartStore: CartStore } ``` Both throw a `ShopkitConfigError` when there is no provider above. `ShopkitContext` is exported for advanced composition. ## Cart ### useCart ```ts theme={null} const { cart, itemCount, status, pending, error, revision, add, updateItem, removeItem, clear, clearCart, refresh } = useCart() ``` Every caller shares the same store. The cart is loaded on first mount and **never created speculatively**. Sum of quantities, for a badge. Mutations in flight. Captured, not thrown. Bumped once per successful mutation made through the store. `{ productId, variantId?, quantity? }`. `null` on failure. Line id. `0` removes the line. Deletes the remembered cart and forgets it. `clearCart` is an alias. ## Catalog hooks All return `AsyncState`: `{ data: T | null; loading: boolean; error: Error | null; refetch(): void }`. Each fetch is aborted on unmount and on every re-run, and a superseded response is discarded, so a search-as-you-type box cannot land an out-of-order result. They are not a cache; an app with TanStack Query or SWR should call the client directly. ### useProducts ```ts theme={null} useProducts(params?: { limit?; cursor?; storefrontId?; currency? }, options?: { enabled?: boolean; initialData?: Page | null }): AsyncState> ``` The product hooks follow the client's currency and **refetch when it changes**. A `currency` parameter prices one read in another currency (`null` for the shop's own). ### useProductSearch ```ts theme={null} useProductSearch(params?: ProductSearchParams, options?: { enabled?; initialData? }): AsyncState> ``` Takes every [`products.search`](/kit/reference/products) parameter. All are primitives, so an inline object literal does not re-fetch. ### useProduct ```ts theme={null} useProduct(productId: string | number | null | undefined, options?: { initialData?: Product | null; storefrontId?: string | null; currency?: string | null }): AsyncState ``` `data` is `null` for a hidden or missing product. ### useCategories ```ts theme={null} useCategories(params?: CategoryListParams, options?: { enabled?; initialData? }): AsyncState> ``` ### useShop ```ts theme={null} useShop(options?: { initialData?: Shop | null }): AsyncState ``` ## Currency ### useCurrency ```ts theme={null} const { currency, selected, baseCurrency, currencies, mode, rate, chargeCurrency, setCurrency, isLoading, error } = useCurrency() ``` The currency the tree browses in, what the shop offers, and the switch. Reads the shop once per client (shared by every caller; needs `checkout:read`). See [Currencies](/kit/concepts/currencies). What prices are shown in: the choice when the shop offers it, else the shop's own. What was asked for (the remembered choice, else the configured default), whether or not the shop offers it. The shop's own currency. `{ code, mode, rate }[]`, base first. Only the base entry when the converter is off; empty while loading. `display`: shown converted, charged in the shop's currency. `charge`: priced and charged in it. Units of `currency` per 1 unit of the shop's currency. What the checkout will charge. Switch and remember. Every product hook refetches, `useCart()` re-reads the same cart, and the next checkout opens in it. `null` returns to the default. True while the shop, and with it the list of currencies, is loading. ```tsx theme={null} function CurrencySwitcher() { const { currency, currencies, setCurrency } = useCurrency() if (currencies.length < 2) return null return ( ) } ``` ### useClientCurrency ```ts theme={null} useClientCurrency(client: ShopkitClient): string | null ``` The bare subscription: `client.currency`, re-rendering when it changes. No shop read. ### useAsync ```ts theme={null} useAsync(operation: (signal: AbortSignal) => Promise, deps: readonly unknown[], options?: { enabled?; initialData? }): AsyncState ``` The primitive the catalog hooks are built on, for a read of your own with the same abort semantics. ## Product and variant selection ### ProductProvider ```tsx theme={null} … // resolved … // React 19 use() … // looks it up … // one request ``` Holds the variant selection for one product and derives everything from it. Renders nothing of its own. A `slug` or `id` lookup re-reads the product when the client's currency changes. With analytics on, it tracks `view_item` once per product. A resolved product, or a promise unwrapped with React 19 `use()` (wrap in ``). Takes precedence over `slug` and `id`. Looks the product up. Walks the catalog; needs React 19 and a ``. Looks the product up by id. Needs React 19 and a ``. Rendered when the product is missing or hidden. Preselect a variant, for `?variant=` deep links. Start on the first non-hidden variant instead of a price range. A formatting fallback, used only when the product does not state its own `product.currency` (a platform older than the field). Passed through to `useProductPrice` and ``. ### useProductState ```ts theme={null} useProductState(): ProductState useOptionalProductState(): ProductState | null // outside a provider ``` Each group with its values, `selected` and `available`. The selection pins one variant. `amount`, `compareAtAmount`, `min`, `max`, `isRange`. The product's own `product.currency`, else the provider's `currency` prop. Format with this. Repairs contradictions instead of refusing. ### Selection hooks | Hook | Returns | | - | - | | `useProductOptions()` | `VariantOptionGroupState[]` | | `useProductOption(idOrName)` | One group by id or name, or `null` | | `useSelectedVariant()` | `ProductVariant \| null` | | `useProductPrice()` | `VariantPriceState & { currency?: string }` | ### useProductAddToCart ```ts theme={null} const { addToCart, canAddToCart, pending, error, missingOptions, buyNow, buying, buyNowError } = useProductAddToCart() ``` Adds the selected variant. A no-op while the selection is incomplete. False until one variant is pinned, while a mutation is in flight, and during a buy-now. The groups still missing a choice, for a "Select a size" prompt. Adds the selected variant and navigates to the hosted checkout. `input` is a `StartCheckoutInput`. True while a buy-now runs, and after it navigated until the page is restored. ### Headless components Each renders **only** what its `children` function returns. | Component | Props | Child receives | | - | - | - | | `` | `children` | `VariantOptionGroupState[]` | | `` | `option` (id or name), `fallback?` | `VariantOptionGroupState` | | `` | `option` (id or name), `fallback?` | `VariantOptionValueState`, once per value | | `` | `fallback?` | `ProductVariant` | | `` | | `VariantPriceState & { currency? }` | | `` | | `ProductAddToCartState` (the `useProductAddToCart` result) | | `` | | `ProductState` | `fallback` renders when the product has no such group, so a component written for "Color" degrades quietly. ```tsx theme={null} {(value) => ( )} ``` ## Images ### ProductImage ```tsx theme={null} // inside // a card // a gallery // fetches; needs ``` Renders a single `` with the CDN URL and `srcSet` resolved. Product precedence: `image`, `product`, the surrounding ``, then a lookup by `productId` or `slug`. CSS pixels. Drives the resize, the `srcSet` and the box. Which image, in display order. A specific image, for example `variant.imageId`. `[]` disables the `srcSet`. `w` descriptors instead; pair with `sizes`. `quality`, `format`, `fit`, `crop` and so on. Defaults to the image's alt text, then the product name, then `""`. Rendered when there is no image. Never a broken ``. `loading="eager"` and `fetchPriority="high"`, for the LCP image. Everything else lazy-loads. Which product and image; see above. Every other `` attribute passes through. ### useProductImage ```ts theme={null} const { src, srcSet, alt, image, product, width, height } = useProductImage({ width: 800 }) ``` The same resolution without rendering, for `next/image`, a CSS background or an og:image. ## Checkout ### useCheckout ```ts theme={null} const { start, redirectToCheckout, buyNow, starting, error, url } = useCheckout() ``` Creates the session without navigating. Creates the session and navigates with `location.assign`. Adds one item to the remembered cart and navigates. True while starting, and after a navigation until the page is restored from the back/forward cache. A navigation that never unloads releases it after 10 seconds. The last handoff URL. A second click while one is in flight is ignored. `input` is a [`StartCheckoutInput`](/kit/reference/checkout); pass `cartId: cart?.id` from `useCart()` where cookies may be blocked (an app builder's preview). ### useOrderConfirmation ```ts theme={null} const { status, orderNumber, outcome, confirmation, loading, error } = useOrderConfirmation(sessionId?, options?) ``` Polls until the order exists, the payment fails terminally, or the caps are reached. Without a `sessionId` it uses the one the kit remembered when the checkout started. With analytics on, a completed order is reported as the `purchase` event once, deduplicated across reloads. `false` never polls. The snapshot the server already took with `shopkit.checkout.confirmation()`. A `completed` or `failed` one is final: nothing is polled, the bought cart and session are forgotten (as a completed poll does), and a completed one is reported as the `purchase`. A pending one is polled from. Report the `purchase` event once the order exists. ```tsx theme={null} // The server read a snapshot; a settled one renders final on the first paint. const { status, orderNumber } = useOrderConfirmation(sessionId, { initialConfirmation }) ``` `timeout` is not a failure. For example "no checkout session to confirm" on a direct visit. ### Checkout ```tsx theme={null} track(orderNumber)} /> ``` The hosted checkout rendered inline in an iframe. Renders one `

` with the frame inside. The session is created once, on mount; changing props afterwards does not rebuild it. It follows the cart: nothing mounts for an empty cart, and emptying the cart takes the frame down. See [Embedded checkout](/kit/concepts/embedded-checkout). Relative URLs resolve against the page. Only the origin is used for the landing. Omitted, the checkout follows the merchant's setting. A checkout that could not start is reported here, never thrown. Called once when the cart settles empty. ## Consent and analytics `` mounts all of this by default; the pieces are public for a page that composes them itself. See [Consent and analytics](/kit/concepts/consent-and-analytics). ### ConsentProvider ```tsx theme={null} {children} ``` Provides one consent store to the tree. Takes every `ConsentStoreOptions` field (`revision`, `cookieName`, `maxAgeDays`, `domain`, `sameSite`, `secure`, `persist`, `initialState`), plus `store` (a `ConsentStore` you built, for example one bridged to a third-party consent platform with `persist: false`) and `lang`. A `` inside one that already exists shares the existing store: one decision per page. ### useConsent / useOptionalConsent ```ts theme={null} const { status, analytics, marketing, open, allows, acceptAll, rejectAll, save, reset, openSettings, closeSettings, store } = useConsent() useOptionalConsent() // the same, or null without a consent provider ``` Undecided is treated as denied. The preferences panel is open. `"necessary"` is always allowed. `{ analytics, marketing }`. Withdraw: forget the decision and show the banner again. `useConsent()` throws without a consent provider above. ### ConsentBanner ```tsx theme={null} // the default accessible dialog {(state) => state.visible && } // headless ``` With no children it renders the kit's styled, accessible dialog; with a render function it renders only what you return. A banner you place replaces the provider's default one. `state` is the consent snapshot plus `visible`, `labels`, `draft`, `setDraft(partial)`, `acceptAll`, `rejectAll`, `save` (saves the draft), `reset`, `openSettings`, `closeSettings`. Leave out the stylesheet. Keep it visible after a decision. `visible` is true while undecided, while the preferences panel is open, or with `showWhenDecided`. The banner renders nothing before hydration unless the provider got `initialState`. ### ConsentSettingsButton ```tsx theme={null} Ändra cookieval ``` A real `