Style the Modal

Customize the visual appearance of the Para Modal to match your application’s design system. Configure branding in the Developer Portal by default, and use configOverrides when a modal instance needs code-level overrides.

Logo Configuration

configOverrides={{
  modalConfig: {
    logo: "https://yourdomain.com/logo.png"
  }
}}

For optimal display, use a logo image with dimensions of 372px x 160px.

Theme Configuration

In v3, the theme system uses OKLCH color mixing to generate a complete, harmonious palette from just two colors: foregroundColor and backgroundColor. You no longer need to specify individual colors for buttons, accents, text, or dark mode variants.

Basic Theme Example

configOverrides={{
  themeConfig: {
    foregroundColor: "#007AFF",
    backgroundColor: "#FFFFFF",
    mode: "light",
    borderRadius: "md",
    font: "Arial, sans-serif"
  }
}}

Dark Mode Configuration

Just provide dark colors for backgroundColor and foregroundColor. The system auto-detects dark mode from the background color lightness and generates an appropriate palette:

configOverrides={{
  themeConfig: {
    foregroundColor: "#0A84FF",
    backgroundColor: "#1C1C1E",
  }
}}

In v3, separate dark mode color properties (darkForegroundColor, darkBackgroundColor, darkAccentColor) are no longer needed. The palette is auto-generated from your foregroundColor and backgroundColor, and dark/light mode is auto-detected from the background color lightness. Use the mode property only if you need to override the auto-detection (e.g., for a background color near the light/dark boundary that gets misclassified).

Foreground Mix Ratio

The foregroundMixRatio controls how much your foregroundColor bleeds into UI surfaces like buttons, inputs, and borders. The default is 0.04.

configOverrides={{
  themeConfig: {
    foregroundColor: "#007AFF",
    backgroundColor: "#FFFFFF",
    foregroundMixRatio: 0.12
  }
}}

Value	Effect
`0.04`	Default, subtle tinting: surfaces stay close to the background color
`0.08`	Moderate tinting: foreground color is more visible in surfaces
`0.15`	Strong tinting: foreground color is more prominent across all surfaces

If your background has color (is not a neutral gray/white/black), the theme system uses the background color’s hue for surface variations. If your background is neutral, the foreground color provides the hue for surfaces via the mix ratio.

Advanced Customization with CSS Overrides

For granular control over specific UI elements, use the cssOverrides property to set raw CSS custom properties. Overrides are applied after the palette is generated — they replace specific generated values without affecting the rest of the theme — and are scoped to the Para modal, so they never leak into your app’s styles.

configOverrides={{
  themeConfig: {
    foregroundColor: "#007AFF",
    backgroundColor: "#FFFFFF",
    mode: "light",
    cssOverrides: {
      "--para-color-primary": "#007AFF",
      "--para-color-accent": "#1A1A2E",
      "--para-color-destructive": "#E74C3C"
    }
  }
}}

cssOverrides is an advanced escape hatch. Most applications will get excellent results using just foregroundColor and backgroundColor. Only use cssOverrides when you need to override a specific generated color.

Where to set overrides

Surface	Where	Scope
`themeConfig.cssOverrides`	In code, on `configOverrides.themeConfig`	This modal instance

The SDK can read CSS override values that already exist on partner config, but the Developer Portal does not expose a CSS override editor today.

Available CSS Variables

These are the custom properties the modal actually consumes, so overriding them takes effect:

Variable	Description
`--para-color-background`	Modal background
`--para-color-foreground`	Primary text color
`--para-color-primary`	Primary accent (buttons, links, active states)
`--para-color-primary-foreground`	Text on primary-colored elements
`--para-color-secondary`	Secondary element backgrounds
`--para-color-secondary-foreground`	Text on secondary elements
`--para-color-muted`	Muted / input backgrounds
`--para-color-muted-foreground`	Placeholder and subtle text
`--para-color-accent`	Accent highlights
`--para-color-accent-foreground`	Text on accent elements
`--para-color-popover`	Popover background
`--para-color-popover-foreground`	Popover text
`--para-color-border`	Border color
`--para-color-input`	Input background
`--para-color-ring`	Focus ring color
`--para-color-destructive`	Destructive / error color
`--para-radius`	Global border radius

To change the font, use the font property (below) — not a CSS override. The font family is applied directly to the modal, not through a --para-* variable.

Custom Fonts

You can use custom fonts by importing them in your global CSS and specifying the font family:

configOverrides={{
  themeConfig: {
    font: "Inter, sans-serif"
  }
}}

Ensure your custom font is loaded before the modal renders for the best user experience.

Password & PIN Screen Theme Limitations

Password and PIN authentication screens are rendered in an iframe. The SDK passes the resolved theme when it builds portal URLs, so iframe screens can reflect the same Developer Portal theme or configOverrides.themeConfig.Dynamic theme changes made after an iframe URL has been generated may not affect that iframe until a new URL is generated.

Complete Theming Example

<ParaProvider
  paraClientConfig={{
    apiKey: process.env.REACT_APP_PARA_API_KEY || "",
  }}
  config={{
    appName: "Your App Name"
  }}
  configOverrides={{
    modalConfig: {
      logo: "https://yourdomain.com/logo.png"
    },
    themeConfig: {
      foregroundColor: "#007AFF",
      backgroundColor: "#FFFFFF",
      mode: "light",
      borderRadius: "md",
      font: "Inter, sans-serif",
      foregroundMixRatio: 0.04
    }
  }}
>
  {children}
</ParaProvider>

Migrating from v2.x Theming

If you’re upgrading from v2.x, see the Migration Guide for a detailed property mapping and before/after examples. Test your theme configuration with our interactive tool:

Get Started

Set Up Project

Add Authentication

Build Wallet UI

Sign with Para

Transact on Chains

Manage Sessions

Add Advanced Features

Debug and Launch

Logo Configuration

Theme Configuration

Basic Theme Example

Dark Mode Configuration

Foreground Mix Ratio

Advanced Customization with CSS Overrides

Where to set overrides

Available CSS Variables

Custom Fonts

Password & PIN Screen Theme Limitations

Complete Theming Example

Migrating from v2.x Theming

Modal Designer

​Logo Configuration

​Theme Configuration

​Basic Theme Example

​Dark Mode Configuration

​Foreground Mix Ratio

​Advanced Customization with CSS Overrides

​Where to set overrides

​Available CSS Variables

​Custom Fonts

​Password & PIN Screen Theme Limitations

​Complete Theming Example

​Migrating from v2.x Theming

​Modal Designer

Modal Designer

Logo Configuration

Theme Configuration

Basic Theme Example

Dark Mode Configuration

Foreground Mix Ratio

Advanced Customization with CSS Overrides

Where to set overrides

Available CSS Variables

Custom Fonts

Password & PIN Screen Theme Limitations

Complete Theming Example

Migrating from v2.x Theming

Modal Designer