Theme Support

Theme Configuration

Provide the theme property on the object you pass into checkout.mount('element-id', { ...config }) after creating the instance with new PayNextCheckout(), as shown in Mount the Checkout.

'light' | 'dark' | 'system'

Theme mode for the checkout UI.

'light': Fixed light theme
'dark': Fixed dark theme
'system': Resolves to browser’s prefers-color-scheme at mount time, then fixed
undefined: Defaults to 'light' and listens for system theme changes

When theme is undefined, the SDK automatically updates when the user changes their system theme preference. When explicitly set (including 'system'), the theme is fixed and does not listen to system changes.

import { PayNextCheckout, type PayNextConfig } from '@paynext/sdk'

const checkout = new PayNextCheckout()

const config: PayNextConfig = {
  clientToken: 'your-client-token',
  environment: 'sandbox',
  apiVersion: '1.0.0',
  theme: 'dark',
}

await checkout.mount('checkout-container', config)

import { PayNextCheckout, type PayNextConfig } from '@paynext/sdk'

const checkout = new PayNextCheckout()

const config: PayNextConfig = {
  clientToken: 'your-client-token',
  environment: 'sandbox',
  apiVersion: '1.0.0',
  theme: 'system',
}

await checkout.mount('checkout-container', config)

import { PayNextCheckout, type PayNextConfig } from '@paynext/sdk'

const checkout = new PayNextCheckout()

const config: PayNextConfig = {
  clientToken: 'your-client-token',
  environment: 'sandbox',
  apiVersion: '1.0.0',
  // theme omitted - defaults to light, listens to system changes
}

await checkout.mount('checkout-container', config)

Payment Button Styling

Payment buttons automatically adapt to the theme:

Apple Pay: style: 'black' (light) / 'white' (dark)
Google Pay: color: 'black' (light) / 'white' (dark)
PayPal: color: 'gold' (light) / 'white' (dark)
Pix: white background with an #e0e0e0 border (light) / #1a1a1a background with a #333 border (dark)
BLIK: black background and border in both themes (the BLIK mark is white on black); the dark theme only softens the border to #333

Custom button styles in styles.ApplePayButton, styles.GooglePayButton, styles.PayPalButton, styles.PixButton, or styles.BlikButton override theme defaults.

Pix Form Theming

Available from SDK version 1.1.0.

The Pix form’s embedded Stripe Payment Element — the email, CPF/CNPJ, and name fields, plus the QR code step — follows the checkout’s light/dark theme automatically. No configuration is required.

Light theme: white field background, dark text
Dark theme: dark field background, light text

Both themes share the same accent color and remove Stripe’s default focus shadow, so the Pix form matches the rest of the checkout’s flat input style.

Changing the theme at runtime (checkout.update({ theme })) re-themes an already-open Pix form immediately — you don’t need to close and reopen it.

Custom Pix Form Colors

Override individual colors and the border radius with styles.PixForm (type PixFormStyles). These map to Stripe’s Appearance API variables, not the --paynext-sdk-* tokens below, since the Pix form renders inside a Stripe-hosted iframe.

pix-form-theme.ts

import { PayNextCheckout, type StylesConfig } from '@paynext/sdk'

const styles: StylesConfig = {
  PixForm: {
    colorPrimary: '#ff4785',
    borderRadius: '4px'
    // colorBackground, colorText, colorDanger, colorTextPlaceholder also available
  }
}

const checkout = new PayNextCheckout()
await checkout.mount('checkout-container', {
  clientToken: 'your-client-token',
  environment: 'sandbox',
  apiVersion: '1.0.0',
  styles
})

Fields you don’t set keep the active theme’s default, and overrides apply to both recurring Pix Automático and one-time Pix. See PixForm for the complete field reference.

BLIK Form Theming

Available from SDK version 1.2.0.

The BLIK form’s embedded Stripe Payment Element, where the customer enters the six-digit code from their banking app, follows the checkout’s light/dark theme automatically. No configuration is required, and it behaves exactly like the Pix form above: the same light/dark field treatment, the same accent color, and no Stripe focus shadow.

Changing the theme at runtime (checkout.update({ theme })) re-themes an already-open BLIK form immediately — you don’t need to close and reopen it.

Custom BLIK Form Colors

Override individual colors and the border radius with styles.BlikForm (type BlikFormStyles, the same shape as PixFormStyles). These map to Stripe’s Appearance API variables, not the --paynext-sdk-* tokens below, since the BLIK form renders inside a Stripe-hosted iframe.

blik-form-theme.ts

import { PayNextCheckout, type StylesConfig } from '@paynext/sdk'

const styles: StylesConfig = {
  BlikForm: {
    colorPrimary: '#000000',
    borderRadius: '4px'
    // colorBackground, colorText, colorDanger, colorTextPlaceholder also available
  }
}

const checkout = new PayNextCheckout()
await checkout.mount('checkout-container', {
  clientToken: 'your-client-token',
  environment: 'sandbox',
  apiVersion: '1.0.0',
  styles
})

Fields you don’t set keep the active theme’s default. They apply to the form where a new BLIK payment is entered; a saved BLIK payment method is charged from the saved-method row without that form. See BlikForm for the complete field reference.

CSS Variables

Override theme tokens by passing styles.cssVariables (type CSSVariablesConfig) when you mount the SDK, or target .checkout / .checkout.dark classes from your stylesheet. Unset values fall back to the active theme defaults.

Variables marked “inherits” are not redefined in dark mode and use the light theme value. Variables marked “same” are explicitly set to the same value in both themes.

Complete Token Reference

Variable	Light default	Dark default	Description
`--paynext-sdk-bg`	`transparent`	`transparent`	Checkout container background
`--paynext-sdk-text`	`#1a1a1a`	`#ffffff`	Primary text color
`--paynext-sdk-border`	`#e0e0e0`	`#404040`	Default border color
`--paynext-sdk-border-focus`	`#6b7280`	`#9ca3af`	Border color on focus
`--paynext-sdk-border-radius`	`12px`	inherits	Global border radius
`--paynext-sdk-input-bg`	`transparent`	`transparent`	Input field background
`--paynext-sdk-input-text`	`hsla(0, 0%, 10%, 0.9)`	`hsla(0, 0%, 90%, 0.9)`	Input text color
`--paynext-sdk-input-focus-shadow`	`0 0 0 1px rgba(13, 118, 110, 0.7), 0 1px 1px 0 rgba(0, 0, 0, 0.07), 0 0 0 4px rgba(13, 118, 110, 0.3)`	same	Focus ring/shadow
`--paynext-sdk-placeholder`	`#9ca3af`	`#6b7280`	Placeholder text color
`--paynext-sdk-error`	`#ef4444`	`#f87171`	Error text color
`--paynext-sdk-error-border`	`#dc2727`	`#f87171`	Error border color
`--paynext-sdk-disabled-bg`	`#ebedef`	`#374151`	Disabled input background
`--paynext-sdk-disabled-text`	`#9ca3af`	`#6b7280`	Disabled input text
`--paynext-sdk-button-bg`	`#0d766e`	`#0d766e`	Submit button background
`--paynext-sdk-button-hover-bg`	`#0d766d25`	inherits	Button hover background
`--paynext-sdk-button-text`	`#ffffff`	`#ffffff`	Button text color
`--paynext-sdk-button-hover-opacity`	`0.7`	`0.8`	Button hover opacity
`--paynext-sdk-card-bg`	`#252525`	`#ffffff`	Card icon container
`--paynext-sdk-card-icon`	`#565656`	`#d1d5db`	Card icon color
`--paynext-sdk-success-bg`	unset (circle `#ecfdf5`, ripples `#d1fae5`)	unset (same)	Background of the success animation: the circle and its ripples. One value colors both. Available in SDK `2.0.1` and later

Override from Config

Pass cssVariables through the styles option when mounting:

config-override.ts

import { PayNextCheckout, type CSSVariablesConfig, type StylesConfig } from '@paynext/sdk'

const cssVariables: CSSVariablesConfig = {
  '--paynext-sdk-bg': '#0b1220',
  '--paynext-sdk-text': '#e2e8f0',
  '--paynext-sdk-button-bg': 'linear-gradient(135deg, #0ea5e9, #6366f1)',
  '--paynext-sdk-border-radius': '14px',
  '--paynext-sdk-input-focus-shadow': 'none' // Remove default focus ring
}

const styles: StylesConfig = { cssVariables }

const checkout = new PayNextCheckout()
await checkout.mount('checkout-container', {
  clientToken: 'your-token',
  environment: 'sandbox',
  apiVersion: '1.0.0',
  styles
})

Set --paynext-sdk-input-focus-shadow to none to disable the default teal focus ring, and use --paynext-sdk-border-focus to color the focused field’s border instead.

Override per Theme

The checkout renders inside an iframe, so your page’s stylesheets can’t override its variables. Set them in cssVariables instead. The values you pass apply in both themes, and styles can’t change after mount. To use different values for light and dark, pick the set that matches the theme when you mount:

theme-overrides.ts

import { PayNextCheckout, type CSSVariablesConfig } from '@paynext/sdk'

const lightTokens: CSSVariablesConfig = {
  '--paynext-sdk-border': '#e5e7eb',
  '--paynext-sdk-border-focus': '#6366f1',
  '--paynext-sdk-input-focus-shadow': '0 0 0 3px rgba(99, 102, 241, 0.2)'
}

const darkTokens: CSSVariablesConfig = {
  '--paynext-sdk-border': '#374151',
  '--paynext-sdk-border-focus': '#818cf8'
}

let checkout = new PayNextCheckout()

async function mountCheckout(isDark: boolean) {
  await checkout.mount('checkout-container', {
    ...config,
    theme: isDark ? 'dark' : 'light',
    styles: { cssVariables: isDark ? darkTokens : lightTokens }
  })
}

Custom cssVariables don’t follow a theme change after mount. checkout.update({ theme }) and the automatic switch when theme is undefined change only the built-in theme values, so your tokens for the previous theme stay applied. If your page switches themes while the checkout is open, unmount it and mount it again with the matching token set:

await checkout.unmount()
checkout = new PayNextCheckout()
await mountCheckout(isDark)

Remounting resets the form, so anything the customer has typed is cleared.

Style Presets

Create reusable style presets for different design systems:

Minimal
Colorful
Brand Colors

minimal-preset.ts

import type { CSSVariablesConfig, StylesConfig } from '@paynext/sdk'

const minimalPreset: StylesConfig = {
  cssVariables: {
    '--paynext-sdk-input-focus-shadow': 'none',
    '--paynext-sdk-border': '#000000',
    '--paynext-sdk-border-focus': '#000000',
    '--paynext-sdk-border-radius': '0px'
  },
  SubmitButton: {
    styles: {
      background: '#000000',
      borderRadius: '0px',
      textTransform: 'uppercase',
      letterSpacing: '1px'
    }
  }
}

colorful-preset.ts

import type { CSSVariablesConfig, StylesConfig } from '@paynext/sdk'

const colorfulPreset: StylesConfig = {
  cssVariables: {
    '--paynext-sdk-input-focus-shadow': '0 0 0 3px rgba(139, 92, 246, 0.2)',
    '--paynext-sdk-border': '#e0e7ff',
    '--paynext-sdk-border-focus': '#8b5cf6',
    '--paynext-sdk-button-bg': '#8b5cf6'
  },
  SubmitButton: {
    styles: {
      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      borderRadius: '12px',
      boxShadow: '0 8px 32px rgba(102, 126, 234, 0.3)'
    }
  }
}

brand-preset.ts

import type { CSSVariablesConfig, StylesConfig } from '@paynext/sdk'

// Define your brand colors
const brand = {
  primary: '#ff6b6b',
  dark: '#2d3436',
  light: '#dfe6e9'
}

const brandPreset: StylesConfig = {
  cssVariables: {
    '--paynext-sdk-border': brand.light,
    '--paynext-sdk-border-focus': brand.primary,
    '--paynext-sdk-input-focus-shadow': `0 0 0 3px ${brand.primary}20`,
    '--paynext-sdk-button-bg': brand.primary,
    '--paynext-sdk-button-text': '#ffffff'
  },
  Input: {
    label: {
      styles: { color: brand.dark, fontWeight: '600' }
    }
  },
  SubmitButton: {
    styles: {
      borderRadius: '10px',
      boxShadow: `0 4px 14px ${brand.primary}40`
    }
  }
}

TypeScript Reference

The SDK exports full type definitions for theme configuration:

types.ts

import { PayNextCheckout, type PayNextConfig } from '@paynext/sdk'
import type { CSSVariablesConfig, ThemeMode, StylesConfig } from '@paynext/sdk'

// Theme mode type
const theme: ThemeMode = 'system' // 'light' | 'dark' | 'system'

// Typed CSS variables
const cssVariables: CSSVariablesConfig = {
  '--paynext-sdk-bg': '#0b1220',
  '--paynext-sdk-text': '#e2e8f0',
  '--paynext-sdk-border': '#1e293b',
  '--paynext-sdk-border-focus': '#3b82f6',
  '--paynext-sdk-input-bg': '#1e293b',
  '--paynext-sdk-input-text': '#f1f5f9',
  '--paynext-sdk-input-focus-shadow': '0 0 0 2px rgba(59, 130, 246, 0.3)',
  '--paynext-sdk-placeholder': '#64748b',
  '--paynext-sdk-error': '#f87171',
  '--paynext-sdk-error-border': '#f87171',
  '--paynext-sdk-disabled-bg': '#374151',
  '--paynext-sdk-disabled-text': '#6b7280',
  '--paynext-sdk-button-bg': '#3b82f6',
  '--paynext-sdk-button-text': '#ffffff',
  '--paynext-sdk-button-hover-bg': '#2563eb',
  '--paynext-sdk-button-hover-opacity': '0.9',
  '--paynext-sdk-border-radius': '8px',
  '--paynext-sdk-card-bg': '#334155',
  '--paynext-sdk-card-icon': '#94a3b8'
}

// Combined styles config
const styles: StylesConfig = {
  cssVariables,
  // Component-level overrides still work alongside cssVariables
  SubmitButton: {
    styles: { fontWeight: '600' }
  }
}

const config: PayNextConfig = {
  clientToken: 'your-client-token',
  environment: 'sandbox',
  apiVersion: '1.0.0',
  theme,
  styles,
}

const checkout = new PayNextCheckout()
await checkout.mount('checkout-container', config)

All CSSVariablesConfig properties are optional. Only override the tokens you need to change.

Getting Started

Use Cases

Customization

Constants

Theme Configuration

Payment Button Styling

Pix Form Theming

Custom Pix Form Colors

BLIK Form Theming

Custom BLIK Form Colors

CSS Variables

Complete Token Reference

Override from Config

Override per Theme

Style Presets

TypeScript Reference

​Theme Configuration

​Payment Button Styling

​Pix Form Theming

​Custom Pix Form Colors

​BLIK Form Theming

​Custom BLIK Form Colors

​CSS Variables

​Complete Token Reference

​Override from Config

​Override per Theme

​Style Presets

​TypeScript Reference

Theme Configuration

Payment Button Styling

Pix Form Theming

Custom Pix Form Colors

BLIK Form Theming

Custom BLIK Form Colors

CSS Variables

Complete Token Reference

Override from Config

Override per Theme

Style Presets

TypeScript Reference