Styling Elements

Mode, tokens with a full accent ramp, Google Fonts, rules scoped to a published class list, preset bare, and restyling live.

Elements paint no background of their own: they take whatever is behind them, so a checkout in a white card looks like part of that card. Everything else comes from brand:

const elements = shopfast.elements({
  items,
  brand: {
    mode: "light",
    fonts: ["Fraunces:wght@500;700", "Inter:wght@400;500;600"],
    tokens: { accent: "#b2452a", text: "#221f1c", border: "#ddd5c9", radius: "4px", font: "Inter, system-ui, sans-serif", fontHeading: "Fraunces, Georgia, serif" },
    rules: {
      ".sf-el-pay": { borderRadius: "999px", letterSpacing: "0.02em" },
      ".sf-el-method[data-selected]": { backgroundColor: "#fbf3f0" },
    },
  },
});

Try every token, font and rule live in the playground: it shows the code as you go.

Mode

mode is "light", "dark" or "auto" (the default, which follows the buyer’s system setting). Set it when your page is always light or always dark, or a dark-mode visitor gets a dark checkout on your white page.

Tokens

Tokens are the broad strokes. Each one becomes a CSS variable every element reads.

Colors take hex, rgb(), hsl() or oklch(). Lengths take px or rem. A value that does not fit is refused with a trace, and the default stays.

The accent ramp

Set accent and elements build eleven steps from it (--sf-el-accent-50 to --sf-el-accent-950) in OKLCH, so hover states, the selected method’s tint, focus rings and links all come from your color rather than a generic blue. The step closest to your accent is your accent exactly; the others keep its hue and are mapped into what screens can show.

Contrast

Elements check text against your colors with the WCAG 2 formula. Leave out onAccent and they pick white or near black, whichever reads better on your accent. When text on the accent, or text on a solid surface, falls under 4.5:1 (WCAG AA), you get a trace with the ratio:

Text on the accent is 1.98:1, below WCAG AA (4.5:1). Pick a darker or lighter accent.

Fonts

An element is its own document, so the fonts your page loads do not reach it. Load them into the elements:

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

Google Fonts only, up to four families, and the address is rebuilt from the family names and weights rather than used as you pass it: any other stylesheet would reach a payment page without going through the rules below. Then name the family in font, fontHeading or fontMono.

Rules

rules is CSS for the published class names, and only those:

rules: {
  ".sf-el-button": { borderRadius: "2px" },
  ".sf-el-field-input:focus-visible": { boxShadow: "0 0 0 3px rgb(178 69 42 / .25)" },
  ".sf-el-method[data-selected]": { borderColor: "#b2452a", backgroundColor: "#fbf3f0" },
  ".sf-el-total-amount": { fontFamily: "Fraunces, Georgia, serif" },
}

• Selectors are one class from the list below, optionally with one state, [data-selected], [data-disabled], [data-loading], [data-invalid], [data-locked], [data-open], [data-empty], [data-applied], [data-checked] or [data-test], and one of :hover, :focus, :focus-visible, :focus-within, :active, :disabled, :checked, or ::placeholder on .sf-el-field-input. Several selectors may share a rule with commas. No element names, ids or combinators.
• Properties may be written borderRadius or "border-radius". Numbers get px where CSS needs a unit.
• Hover rules only apply on devices with a mouse, so phones never get a stuck hover.
• !important is removed. Your rules already win over the defaults.
• var() may read the elements’ own tokens (var(--sf-el-accent)), nothing else.

What is refused

A checkout that can be restyled freely can be made to lie about what it charges: hide the total, cover the pay button, dress a decline up as a success. So these are refused everywhere:

Totals, the pay button, prices and the legal texts are protected (marked in the class list). They take colors, borders, radius, padding, shadows and type, and nothing that could hide them: no opacity, visibility, display, size or margins, text no smaller than 12px, solid colors only, and text at 3:1 contrast or better against its background.

Every refusal is a trace, never a silent drop:

elements.on("trace", (e) => console.warn(e.message));
// Rule ".foo" refused: .foo is not a ShopFast Elements class.
// .sf-el-pay { position } refused: position can move parts of the checkout out of place.

The checks after your rules

After your rules apply, each element checks its protected parts in the browser: still visible, inside the element, not see-through, at least 10px and readable against their background. If one fails, that element turns your rules off and says why:

Rules turned off in the payButton element: .sf-el-pay cannot be read against its background with them.

The class names

These are a promise: once a class is on this list it keeps existing and keeps meaning the same thing, even when what is behind it is rewritten. New classes are only ever added.

Starting from nothing

preset: "bare" strips the elements down to structure: no borders, no backgrounds, no radius, no padding. Layout, type and focus rings stay, so it is still usable while you build your own look with rules.

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

Changing the brand later

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

Restyles every element in place: no remount, no flash, and the buyer keeps what they typed.