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.
A theme
Section titled “A theme”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" }, },};presetstarts 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.labelsis"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.primarycolours the picked method and the checkout element’s Pay button;colors.primaryTextis the button’s text.
Every token, with its default, is on the PesepayTheme reference page.
Pass it to the elements
Section titled “Pass it to the elements”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.
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();import type { CheckoutOutcome } from "@pesepay/js";import { CheckoutElement, Elements } from "@pesepay/react";import { appearance } from "./appearance.js";
export function ThemedCheckout({ referenceNumber, onFinished,}: { referenceNumber: string; onFinished: (outcome: CheckoutOutcome) => void;}) { return ( // Every element inside takes the theme and the font. <Elements options={appearance}> <CheckoutElement options={{ referenceNumber }} onFinished={(event) => onFinished(event.outcome)} onLoadError={(event) => { if (event.fallbackUrl) window.location.assign(event.fallbackUrl); }} /> </Elements> );}<script setup lang="ts">import type { CheckoutOutcome } from "@pesepay/js";import { CheckoutElement, Elements } from "@pesepay/vue";import { appearance } from "./appearance.js";
const props = defineProps<{ referenceNumber: string }>();const emit = defineEmits<{ finished: [outcome: CheckoutOutcome] }>();
function leave(fallbackUrl: string | undefined): void { if (fallbackUrl) window.location.assign(fallbackUrl);}</script>
<template> <!-- Every element inside takes the theme and the font. --> <Elements :options="appearance"> <CheckoutElement :options="{ referenceNumber: props.referenceNumber }" @finished="(event) => emit('finished', event.outcome)" @load-error="(event) => leave(event.fallbackUrl)" /> </Elements></template>import { Component, computed, input, output } from "@angular/core";import type { CheckoutOutcome } from "@pesepay/js";import { CheckoutElement, Elements } from "@pesepay/angular";import { appearance } from "./appearance";
@Component({ selector: "app-themed-checkout", imports: [Elements, CheckoutElement], template: ` <!-- Every element inside takes the theme and the font. --> <pesepay-elements [options]="appearance"> <pesepay-checkout-element [options]="options()" (finished)="finished.emit($event.outcome)" (loadError)="leave($event.fallbackUrl)" /> </pesepay-elements> `,})export class ThemedCheckoutComponent { readonly referenceNumber = input.required<string>(); readonly finished = output<CheckoutOutcome>(); protected readonly appearance = appearance; protected readonly options = computed(() => ({ referenceNumber: this.referenceNumber(), }));
leave(fallbackUrl: string | undefined): void { if (fallbackUrl) window.location.assign(fallbackUrl); }}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.
Web fonts
Section titled “Web 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.
cssSrcmust be a Google Fontscss2URL. 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.familyonly if the customer has the font installed.
What a theme can’t do
Section titled “What a theme can’t do”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.
What’s next
Section titled “What’s next”- Your own method picker: one element per method, all sharing one theme