Skip to content

Appearance and theming

Every element takes a theme: colours, fonts, spacing, labels and states, from a fixed list of tokens. Set it once for a group of elements, and every element in the group uses it.

The elements are isolated from your page’s CSS. The in-page elements render inside a shadow root and the card fields inside a frame on a Pesepay origin, so a rule in your stylesheet doesn’t reach them, and theirs don’t reach your page. The theme is how you style them.

appearance.ts
import type { ElementsOptions } from "@pesepay/js";
// One look for every element in the group. Only these token names are
// accepted: the theme is a fixed vocabulary, not a stylesheet.
export const appearance: ElementsOptions = {
// The card fields are in their own frame, so they need the font passed here.
fonts: [{ cssSrc: "https://fonts.googleapis.com/css2?family=Inter:wght@400;600" }],
theme: {
preset: "flat",
labels: "floating",
colors: { primary: "#0f766e", borderFocus: "#0f766e", error: "#b91c1c" },
fonts: { family: "Inter, system-ui, sans-serif", size: "15px" },
spacing: { borderRadius: "8px", padding: "12px", gap: "16px" },
},
};
  • preset starts from a ready-made look: "night" (dark fields) or "flat" (no visible border, on a light grey fill). Any token you set overrides the preset’s value. A preset sets colours, border radius and the focus ring only.
  • labels is "above", "floating" (inside the field, moving up once it has focus or a value) or "hidden". A hidden label is still read by screen readers.
  • colors.primary colours the picked method and the checkout element’s Pay button; colors.primaryText is the button’s text.

Every token, with its default, is on the PesepayTheme reference page.

Pass the theme and fonts where the group is created: elements() in JavaScript, the options of <Elements> in the components. A change to them is applied to every element in the group. The code is built and type-checked against the published packages.

src/themed-checkout.ts
import { loadPesepay } from "@pesepay/js";
import { appearance } from "./appearance.js";
const container = document.querySelector<HTMLElement>("#checkout")!;
const message = document.querySelector<HTMLElement>("#payment-message")!;
// Your server created the transaction and wrote its reference number here.
const referenceNumber = container.dataset.referenceNumber!;
async function start(): Promise<void> {
// Null if the runtime could not load, for example behind a content blocker.
const pesepay = await loadPesepay();
if (!pesepay) {
message.textContent = "Payments are unavailable. Please try again later.";
return;
}
// Every element created from this group takes the theme and the font.
const elements = pesepay.elements(appearance);
const checkout = elements.create("checkout", { referenceNumber });
checkout.on("finished", (event) => {
if (event.outcome === "succeeded") window.location.assign("/order-complete");
});
checkout.on("loaderror", (event) => {
if (event.fallbackUrl) window.location.assign(event.fallbackUrl);
});
checkout.mount(container);
}
void start();

A theme can also be set on the instance, with loadPesepay({ theme }), and on one element, with its theme option. The three are merged in that order, section by section, so an element that overrides colors keeps the group’s fonts.

The card fields are in their own frame, so a font your page loads does not reach them. Pass it in fonts and name it in theme.fonts.family, as above.

  • cssSrc must be a Google Fonts css2 URL. Any other URL throws, and so do more than 8 fonts. A stylesheet you write yourself is not accepted, because a font can be built so that each digit typed fetches its own file.
  • Your page’s Content-Security-Policy needs nothing more: the fonts load inside the frame.
  • The mobile and scan elements render in your page, so they use the fonts your page already loads. The Mastercard and Zimswitch form is the card provider’s own; it uses theme.fonts.family only if the customer has the font installed.

Only known token names are accepted, and a value is dropped (the default is used) if it is longer than 200 characters or contains ;, {, }, <, >, \ or /*. Arbitrary CSS is left out on purpose: in card fields it would let a stylesheet read what the customer types, for example through background-image: url(...) rules.