PCE's no-code theming capabilities allow you to fully customize the visual experience of your widget while preserving platform security and compliance. You can align the widget with your brand identity—without modifying core functionality or interacting with sensitive payment or card data.

This ensures that your users experience a consistent, trusted interface across payment, vaulting, and card flows.

Customization is especially useful when you want to:

Maintain brand consistency across your application
Improve user trust and conversion with familiar UI
Deliver a cohesive experience across embedded flows

How Theming Works

The theming system is built on a token-based design framework powered by CSS variables. Instead of modifying base styles, you override specific design tokens to apply your branding.

Theming Architecture

Base Styles (globals.css) Contains system-defined design tokens and default styling. This file is managed internally and should not be modified.
Theme Overrides (theme.css) Contains only the variables you override to reflect your brand identity.

📘
The load order is critical — globals.css must be loaded before theme.css. If the order is incorrect, your custom styles may not be applied.

Customization Capabilities

You can define your theme during Widget Initialization using the theme attribute. If no theme is provided, the system automatically applies a default theme.

What You Can Customize

Category	What You Control
Colors	Brand colors for buttons, backgrounds, and interactive elements
Typography	Font families to match your brand identity
Shape	Border radius for inputs, buttons, and containers
Mode	Overall appearance (Light / Dark / Default)

Supported Theme Properties

Category	Property	Description
Color	`primary`	Core brand color used for buttons and key actions (Hex format recommended)
	`primaryForeground`	Text/icon color displayed on primary elements
	`ring`	Focus state outline color for interactive components
Radius	`base`	Controls border radius (in `rem`) for UI elements
Typography	`fontSans`	Primary font family (e.g., Montserrat, Inter, Roboto)
	`fontSerif`	Secondary font family (e.g., Playfair Display, Source Serif 4)
Mode	`LIGHT`, `DARK`, `DEFAULT`	Defines the base theme appearance

Design Guidance (Quick Reference)

Style Preference	Recommended `radius.base`
Sharp / Geometric	`0rem`
Slightly Rounded	`0.25rem`
Standard Rounded	`0.5rem`
Fully Rounded / Pill	`1rem`

Sample Theme Configuration

theme: {
  color: {
    primary: "#043673",
    primaryForeground: "#FBFBFA",
    ring: "#043673"
  },
  radius: {
    base: "0.5rem"
  },
  typography: {
    fontSans: "Montserrat",
    fontSerif: "Source Serif 4"
  }
},
mode: "LIGHT"

Branding Best Practices

To ensure a consistent and accessible experience:

Use Hex color format for all color values
Maintain a minimum 4.5:1 contrast ratio between primary and foreground colors
Align the --ring color with your primary brand color for consistent focus states
Ensure custom fonts are imported before usage (e.g., Google Fonts or self-hosted)
Validate your theme across all UI states (hover, focus, error, disabled)