Elements

Elements is in public beta. It works and it takes real payments, but the API can still change and a few things are missing (see Known limits at the bottom). If you build on it now, pin a copy of your integration code somewhere you can find it again, and tell us what breaks.

What this is

The Embed SDK opens our checkout in a modal on top of your page. Elements is the other option: you get the checkout as separate pieces - the cart summary, the email field, the payment method list, the pay button - and you decide where each one goes and what it looks like. The obvious question is why you’d want that when the modal already works. Two reasons, and if neither applies to you, use the Embed SDK, it’s less work:

The checkout is part of your page, not a layer over it. It sits in your layout, in your column, next to your product photography.
It wears your brand. Your colours, your typeface, your corner radius, your spacing.

The trade-off is that you’re now responsible for the layout, and there’s more to get wrong.

Live demo

A pretend shop with the all-in-one element in its sidebar, wearing that shop’s brand

Quick start

One script tag, no build step, no package to install:

<script src="https://checkout.komerza.com/elements/elements.iife.js"></script>

Then a div to mount into, and four lines:

<div id="checkout"></div>

<script>
  const komerza = Komerza();

  const elements = komerza.elements({
    items: [{ productId: "YOUR_PRODUCT_ID", variantId: "YOUR_VARIANT_ID", quantity: 1 }]
  });

  elements.create("checkout").mount("#checkout");
</script>

That’s a complete, working checkout: cart, email, payment methods, terms, and a pay button. It’s the checkout element - everything in one piece. Most integrations should start here and only split it up if they actually need to.

The elements

elements.create(type) takes one of these:

Type	What it renders
`checkout`	All of it in one element - cart, email, payment methods, terms, pay button
`summary`	The cart: line items, quantity controls, discounts, total
`email`	The buyer’s email address, with validation
`payment`	The payment method list, and the chosen gateway rendered in place
`coupon`	A coupon code field
`consent`	Terms acceptance and the marketing opt-in
`billingAddress`	Billing address, where the store or gateway requires one
`customFields`	Any custom fields configured on the product

Every element you create from the same elements(...) call shares one cart. Change the quantity in summary and the total in checkout updates on its own - you don’t wire that up.

const elements = komerza.elements({ items: [...] });

elements.create("summary").mount("#summary");
elements.create("email").mount("#email");
elements.create("payment").mount("#payment");

How it works

Worth two minutes, because it explains most of the rules further down. Each element is an iframe served from checkout.komerza.com. Card numbers, the buyer’s email and the order itself never touch your page or your JavaScript - which is the point, and it’s what keeps your PCI scope where it is. Alongside your elements we mount one hidden frame, the controller. It owns the cart, talks to our backend, and is the only thing allowed to create an order. Your elements don’t talk to each other directly; they send changes to the controller and it tells everyone what the new state is. That’s why two elements can never disagree about the total. Two consequences you’ll actually notice:

Your JavaScript can’t reach inside an element. Cross-origin, deliberately. Everything you need comes through elements.on(...) and the methods below.
Elements paint no background of their own, in any theme. They inherit whatever’s behind them, so a checkout in a white card looks like part of that card.

Styling

This is the part Elements exists for.

Tokens

tokens are the broad strokes. Set an accent colour and we regenerate the whole primary ramp from it, so it reaches everything that reads that ramp rather than just the pay button.

const elements = komerza.elements({
  items: [...],
  brand: {
    mode: "light",              // "light" | "dark" | "auto" (default)
    tokens: {
      accent: "#b2452a",        // hex - the full ramp is derived from this
      text: "#221f1c",
      textMuted: "#6b635a",
      border: "#ddd5c9",
      surface: "#ffffff",
      surfaceSunken: "#f7f5f2",
      danger: "#b91c1c",
      success: "#15803d",
      warning: "#b45309",
      radius: "2px",
      gap: "1rem",
      font: "Inter, system-ui, sans-serif",
      fontMono: "ui-monospace, Menlo, monospace"
    }
  }
});

Set mode explicitly if your page is always light or always dark. The default follows the buyer’s OS setting, so a permanently light page viewed by someone in dark mode gets a dark checkout on a white panel.

Fonts

An element is a separate document from your page, so a font your page loads is not available to it - the checkout will quietly fall back to a system face. Load fonts into the elements explicitly:

brand: {
  fonts: [
    "Inter:wght@400;500;600",
    { family: "Fraunces", weights: [500, 700] },
    "https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@700"
  ],
  tokens: { font: "Inter, system-ui, sans-serif" }
}

Google Fonts only, and we rebuild the URL from the parts rather than using what you pass. Any other stylesheet would be applied to a payment page without passing through the rules sanitizer below, which would defeat the whole thing.

Rules

rules is CSS, scoped to a fixed vocabulary of class names:

brand: {
  rules: {
    ".kmrza-button": { "border-radius": "2px", "letter-spacing": "0.04em" },
    ".kmrza-field-input": { "border-radius": "2px", "border-color": "#ddd5c9" },
    ".kmrza-method": { "border-radius": "2px" },
    ".kmrza-method[data-selected]": {
      "border-color": "#b2452a",
      "background-color": "#fbf3f0"
    },
    ".kmrza-total-amount": { "font-family": "Fraunces, Georgia, serif" }
  }
}

Selectors must be a single class from the list below, optionally narrowed by one state attribute ([data-selected], [data-disabled], [data-loading], [data-invalid], [data-locked]) and one pseudo-class (:hover, :focus, :focus-visible, :active, :disabled, :checked). No descendant selectors, no element names, no ids. That’s narrower than real CSS on purpose. A checkout that can be restyled arbitrarily can be made to lie about what it charges - hide the total, cover the pay button, dress a decline up as a success. So a handful of properties are refused (position, content, z-index, pointer-events, transform, clip-path, and anything that fetches a URL), and !important is stripped. Everything cosmetic is yours. Anything we refuse is reported, never dropped silently:

elements.on("trace", (e) => console.warn(e.message));
// → brand: Rule ".foo" refused - .foo is not a Komerza hook.

The class names

Group	Classes
Fields	`.kmrza-field` `.kmrza-field-label` `.kmrza-field-input` `.kmrza-field-hint` `.kmrza-field-error`
Buttons	`.kmrza-button` `.kmrza-button-primary` `.kmrza-button-secondary` `.kmrza-button-outline` `.kmrza-button-ghost` `.kmrza-button-danger`
Cart	`.kmrza-summary` `.kmrza-line-item` `.kmrza-line-item-image` `.kmrza-line-item-name` `.kmrza-line-item-option` `.kmrza-line-item-qty` `.kmrza-line-item-price`
Totals	`.kmrza-discount` `.kmrza-total` `.kmrza-total-label` `.kmrza-total-amount`
Payment	`.kmrza-payment` `.kmrza-method-list` `.kmrza-method` `.kmrza-method-icon` `.kmrza-method-label` `.kmrza-method-badge` `.kmrza-method-panel`
Gateway UI	`.kmrza-panel` `.kmrza-heading` `.kmrza-subheading` `.kmrza-alert` `.kmrza-alert-title` `.kmrza-alert-text` `.kmrza-badge` `.kmrza-spinner`
Element roots	`.kmrza-checkout` `.kmrza-coupon` `.kmrza-consent` `.kmrza-billing` `.kmrza-custom-fields` `.kmrza-protection` `.kmrza-skeleton`
Misc	`.kmrza-email` `.kmrza-disclosure` `.kmrza-interval` `.kmrza-overlay` `.kmrza-overlay-panel` `.kmrza-overlay-close`

These are a promise. Once a class is on this list it keeps existing and keeps meaning the same thing, even as we rewrite what’s behind it.

Starting from nothing

If you’d rather build the whole appearance yourself, preset: "bare" strips our cosmetics down to structure - no borders, no backgrounds, no radius, no padding:

brand: { preset: "bare", rules: { /* all yours */ } }

Changing the brand later

elements.update({ brand: { tokens: { accent: "#0f766e" } } });

Restyles in place. No remount, no flash.

Events

elements.on("error", (e) => {
  console.error(e.type, e.code, e.message);
});

Event	When
`ready`	An element has loaded and is interactive
`change`	The buyer changed something - method chosen, quantity edited, email entered
`error`	Anything went wrong, anywhere
`resize`	An element changed height
`focus`	An element took focus
`blur`	An element lost focus
`navigate`	The buyer is being handed to a gateway that needs its own window
`trace`	Diagnostics, including refused brand rules
`loaderror`	An element’s frame failed to load at all

error is the one to handle. Everything that can fail arrives there in one shape, so you don’t have to watch each element separately:

elements.on("error", (e) => {
  // e.type   - "load" | "session" | "validation" | "order" | "payment"
  // e.code   - the backend's own code, when there is one: "OUT_OF_STOCK",
  //            "EMAIL_DOMAIN_REJECTED", "COUPON_INVALID"
  // e.element - which element raised it, if it came from one
  // e.recoverable - true when the buyer can just try again
});

Handle e.code where you can. It’s the part that tells you what to actually do - “out of stock” wants a different response from “that card was declined”.

Taking payment

The checkout element has its own pay button and drives the whole thing. Nothing else to do. If you’ve split the elements up and want your own button, call confirmPayment yourself:

const result = await komerza.confirmPayment({
  elements,
  returnUrl: "https://yourshop.com/thank-you"
});

if (result.error) {
  console.error(result.error.code, result.error.message);
} else {
  console.log("order", result.order.id);
}

returnUrl matters for the gateways that take over the whole window - without it there’s nowhere to send the buyer back to. Most gateways render inline and never leave your page, but some can’t.

Letting the buyer change their mind

Once an order exists the cart is locked, so a buyer who spots a typo isn’t stuck:

elements.edit(); // unlocks the cart and returns to the form

A complete example

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Feldspar Supply</title>
  </head>
  <body>
    <main>
      <h1>Kiln-fired stoneware</h1>
      <div id="checkout"></div>
    </main>

    <script src="https://checkout.komerza.com/elements/elements.iife.js"></script>
    <script>
      const komerza = Komerza();

      const elements = komerza.elements({
        items: [
          { productId: "0f6294be-25d6-4ced-96df-7d500608c54d",
            variantId: "96f846e5-5f22-46a2-97b3-a1c88f685577",
            quantity: 1 }
        ],
        locale: "en",
        brand: {
          mode: "light",
          fonts: ["Inter:wght@400;500;600"],
          tokens: {
            accent: "#b2452a",
            text: "#221f1c",
            border: "#ddd5c9",
            radius: "2px",
            font: "Inter, system-ui, sans-serif"
          },
          rules: {
            ".kmrza-button": { "border-radius": "2px" },
            ".kmrza-field-input": { "border-radius": "2px" },
            ".kmrza-method": { "border-radius": "2px" },
            ".kmrza-method[data-selected]": { "border-color": "#b2452a" }
          }
        }
      });

      // showSummary opts into the product details; the default is a compact total
      elements.create("checkout", { showSummary: true }).mount("#checkout");

      elements.on("error", (e) => console.error(e.type, e.code, e.message));
    </script>
  </body>
</html>

Content Security Policy

If your site sends a CSP, elements need two directives:

frame-src https://checkout.komerza.com;
script-src https://checkout.komerza.com;

Using nonces? Pass yours in and we’ll put it on every frame we create:

const komerza = Komerza(undefined, { nonce: "abc123" });

Known limits

Straight list of what isn’t there yet, so you don’t find out the hard way.

No npm package or React wrapper. Script tag only for now.
No currency selector element. Adaptive currency still works; there just isn’t a picker.
The API can change. It’s a beta. We’ll tell you before anything breaks, but treat it as provisional.

Which one should I use?

Use the Embed SDK

You want a buy button that opens checkout in a modal. It’s a script tag and a data attribute, and it’s done in five minutes.

Use Elements

You want checkout inside your page, laid out and styled as part of your design, and you’re willing to own the layout.

Get Started

Store Setup

Storefront Builder

Orders & Customers

Grow

Payment Setup

Integration Guides

Account

What this is

Live demo

Quick start

The elements

How it works

Styling

Tokens

Fonts

Rules

The class names

Starting from nothing

Changing the brand later

Events

Taking payment

Letting the buyer change their mind

A complete example

Content Security Policy

Known limits

Which one should I use?

Use the Embed SDK

Use Elements

​What this is

Live demo

​Quick start

​The elements

​How it works

​Styling

​Tokens

​Fonts

​Rules

​The class names

​Starting from nothing

​Changing the brand later

​Events

​Taking payment

​Letting the buyer change their mind

​A complete example

​Content Security Policy

​Known limits

​Which one should I use?

Use the Embed SDK

Use Elements

What this is

Quick start

The elements

How it works

Styling

Tokens

Fonts

Rules

The class names

Starting from nothing

Changing the brand later

Events

Taking payment

Letting the buyer change their mind

A complete example

Content Security Policy

Known limits

Which one should I use?