Appearance & theming

Named themes

lightning("init", { theme: "light" }); // "light" | "dark" | "auto"

"auto" follows the visitor’s prefers-color-scheme.

Custom design tokens

Pass a token object instead of a name to match your brand. Tokens map to CSS custom properties inside the banner’s shadow root, and any token you omit falls back to the base:

lightning("init", {
  theme: {
    surface: "#ffffff",
    text: "#14151a",
    accent: "#ffd400",
    accentText: "#14151a",
    border: "#e5e7eb",
    radius: "10px",
    fontFamily: "Inter, system-ui, sans-serif",
    // …textMuted, secondary, secondaryText, overlay
  },
});

Which base do the tokens merge over?

A custom theme is your tokens layered on top of a base. Choose that base with an optional base key — "auto" (the default), "light", or "dark":

lightning("init", {
  theme: {
    base: "auto", // "auto" (default) | "light" | "dark"
    accent: "#ffd400",
  },
});

"auto" — follows the visitor’s prefers-color-scheme, so the same tokens sit on the light base by day and the dark base at night. Supply only the tokens that should differ from the built-in base (typically accent, radius, fontFamily) and they carry across both schemes.
"light" / "dark" — pins the base for every visitor, ignoring their OS setting.

Privacy-policy link

Set privacyPolicyUrl to show a link to your privacy policy in the preferences modal footer (it opens in a new tab). Omit it and no link appears. The link label is customisable via text.privacyPolicy.

lightning("init", {
  privacyPolicyUrl: "https://example.com/privacy",
  text: { privacyPolicy: "Privacy policy" }, // optional label override
});

Position & floating button

lightning("init", {
  position: "bottom", // "bottom" | "top" | "bottom-left" | "bottom-right"
  showFloatingButton: true, // persistent re-open button after a decision
  floatingButtonPosition: "bottom-left",
});

White-labelling

lightning("init", { hideBranding: true }); // hides the "Powered by Lightning" footer