Skip to main content
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
  }
}}
ValueEffect
0.04Default, subtle tinting: surfaces stay close to the background color
0.08Moderate tinting: foreground color is more visible in surfaces
0.15Strong 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

SurfaceWhereScope
themeConfig.cssOverridesIn code, on configOverrides.themeConfigThis 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:
VariableDescription
--para-color-backgroundModal background
--para-color-foregroundPrimary text color
--para-color-primaryPrimary accent (buttons, links, active states)
--para-color-primary-foregroundText on primary-colored elements
--para-color-secondarySecondary element backgrounds
--para-color-secondary-foregroundText on secondary elements
--para-color-mutedMuted / input backgrounds
--para-color-muted-foregroundPlaceholder and subtle text
--para-color-accentAccent highlights
--para-color-accent-foregroundText on accent elements
--para-color-popoverPopover background
--para-color-popover-foregroundPopover text
--para-color-borderBorder color
--para-color-inputInput background
--para-color-ringFocus ring color
--para-color-destructiveDestructive / error color
--para-radiusGlobal 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:

Modal Designer