Migrating from Para v2.x to v3.0

Documentation Index

Fetch the complete documentation index at: https://docs.getpara.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Summary of Breaking Changes

1. foregroundColor now drives the entire UI palette — buttons, accents, rings, and primary colors are all generated from it via OKLCH color space. Previously, foregroundColor was the text/icon color; that role is now auto-generated from the background.
2. accentColor is deprecated — it still works for backward compatibility (and takes precedence over foregroundColor when both are provided), but you should migrate to using foregroundColor instead.
3. Dark mode variant colors removed — darkForegroundColor, darkBackgroundColor, and darkAccentColor no longer exist. Just provide your dark colors as backgroundColor and foregroundColor directly — the system auto-detects dark/light mode from the background color lightness.
4. customPalette, customFontSizes, customBorderRadii removed — replaced by cssOverrides for advanced cases.
5. overlayBackground removed from the theme type.
6. oAuthLogoVariant removed from the theme type.
7. New properties added — foregroundMixRatio and cssOverrides.
8. Portal URL helpers now return { url, fullUrl } - default modal users do not need to change anything, but custom UI consumers that read portal URL fields directly should review the Portal URL Return Shape section.

​

Property Mapping

​

Before & After

paraModalConfig={{
  theme: {
    foregroundColor: "#333333",
    backgroundColor: "#FFFFFF",
    accentColor: "#007AFF",

    darkForegroundColor: "#FFFFFF",
    darkBackgroundColor: "#1C1C1E",
    darkAccentColor: "#0A84FF",

    mode: "light",
    borderRadius: "md",
    font: "Inter, sans-serif",
    overlayBackground: "rgba(0, 0, 0, 0.5)",
    oAuthLogoVariant: "default",

    customPalette: {
      text: {
        primary: "#333333",
        secondary: "#666666"
      },
      primaryButton: {
        surface: {
          default: "#007AFF",
          hover: "#0056CC"
        }
      }
    }
  }
}}

​

Detailed Changes

// v2.x
theme: {
  foregroundColor: "#333333",
  backgroundColor: "#FFFFFF",
  accentColor: "#007AFF",
  darkForegroundColor: "#FFFFFF",
  darkBackgroundColor: "#1C1C1E",
  darkAccentColor: "#0A84FF",
}

// v3.0 — dark mode is auto-detected from the background color
theme: {
  foregroundColor: "#0A84FF",
  backgroundColor: "#1C1C1E",
}

theme: {
  foregroundColor: "#0A84FF",
  backgroundColor: "#4A4A4A", // ambiguous lightness
  mode: "dark" // override: treat as dark
}

// v2.x
theme: {
  customPalette: {
    primaryButton: {
      surface: {
        default: "#007AFF",
        hover: "#0056CC"
      }
    },
    text: {
      secondary: "#666666"
    }
  }
}

// v3.0
theme: {
  foregroundColor: "#007AFF",
  backgroundColor: "#FFFFFF",
  cssOverrides: {
    "--para-color-primary": "#007AFF",
    "--para-color-muted-foreground": "#666666"
  }
}

theme: {
  foregroundColor: "#007AFF",
  backgroundColor: "#FFFFFF",
  foregroundMixRatio: 0.12  // stronger accent presence
}

theme: {
  foregroundColor: "#007AFF",
  backgroundColor: "#FFFFFF",
  cssOverrides: {
    "--para-color-destructive": "#E74C3C",
    "--para-radius": "0.75rem"
  }
}

​

Backward Compatibility

​

Configuration moves to the partner record

​

What to do instead

​

Before & After

paraModalConfig={{
  oAuthMethods: ["GOOGLE", "APPLE"],
  disableEmailLogin: false,
  twoFactorAuthEnabled: true,
  isGuestModeEnabled: false,
  theme: {
    foregroundColor: "#007AFF",
    backgroundColor: "#FFFFFF",
  },
}}

​

New enforcement behavior

​

Portal URL Return Shape

​

Who needs to care

• Default modal users (<ParaModal />): No action required. The modal consumes the new fields internally.
• Custom UI consumers (callers of signUpOrLogIn, verifyOAuth, verifyNewAccount, onStatePhaseChange, etc. who read passkeyUrl / passwordUrl / pinUrl / loginUrl themselves): read the note below.
• Callers of PortalUrlService.constructPortalUrl / PortalUrlService.getLoginUrl, or subclasses that call ParaCore.constructPortalUrl directly: the return value is now { url, fullUrl } instead of string. Update your call sites to destructure.

​

What changed on the auth state types

// v2
redirectCallbacks: {
  onOAuthUrl: (url: string) => {},
}

// v3
redirectCallbacks: {
  onOAuthUrl: (url: string, fullUrl?: string) => {},
}

​

Picking which URL to open

​

Custom UI example

// v2 — still works in v3, but you miss out on the preloaded iframe optimization
const { passkeyUrl, passwordUrl, pinUrl } = authStateInfo;
window.open(passkeyUrl ?? passwordUrl ?? pinUrl, "ParaPortal", "popup");

// v3 — keep the short URL for popups; use *FullUrl for preloaded iframe nav
const { passkeyUrl, passkeyFullUrl, passwordUrl, passwordFullUrl, pinUrl, pinFullUrl } = authStateInfo;

// Popups: short URL is fine
window.open(passkeyUrl ?? passwordUrl ?? pinUrl, "ParaPortal", "popup");

// Preloaded iframe: point at the full URL instead
iframeRef.current.src = passkeyFullUrl ?? passwordFullUrl ?? pinFullUrl ?? "";

​

Service-layer callers (advanced)

// v2
const url: string = await portalUrlService.constructPortalUrl("loginAuth", opts);
const loginUrl: string = await portalUrlService.getLoginUrl(opts);

// v3
const { url, fullUrl } = await portalUrlService.constructPortalUrl("loginAuth", opts);
const { url: loginUrl, fullUrl: loginFullUrl } = await portalUrlService.getLoginUrl(opts);