Passport Embed - Customization

The Passport Embed widget is fully themeable, allowing you to match its appearance to your application's design system. You can customize colors, fonts, border radius, padding, transition timing, and z-index positioning.

Collapse Mode

With Passport Embed, you can control the widget’s collapsible behavior and how it is displayed relative to your page layout.

There are three options for collapse mode:

• "shift" (default): the widget is embedded in the flow and expanding it will push/shift surrounding content (useful if placing at top of a page, for example).
• "overlay": the widget will overlay on top of content when expanded (using CSS position:absolute or similar, on top of the page, with an overlay background perhaps – the overlayZIndex theme can be used to adjust stacking).
• "off": collapse functionality is disabled; the widget is always fully expanded (use this if you want the full widget visible at all times in a particular spot).

You can experiment with these modes to see which best fits your UI.

Using Built-in Themes

Passport Embed provides two built-in themes: DarkTheme and LightTheme. You can import them from the package and pass them directly to the widget’s theme prop. By default, the widget will use DarkTheme.

import { PassportScoreWidget, DarkTheme, LightTheme } from "@human-tech/passport-embed";
 
<PassportScoreWidget
  apiKey="<YOUR_API_KEY>"
  scorerId="<YOUR_SCORER_ID>"
  generateSignatureCallback={generateSignature}
  theme={DarkTheme} // or LightTheme
/>

If your app supports dynamic theming, you can toggle between these based on the user's preference:

const theme = isDarkMode ? DarkTheme : LightTheme;

These built-in themes provide a solid foundation and follow best practices for accessibility and contrast.

Extending or Overriding Theme Properties

You can also override specific theme values by spreading one of the defaults and replacing the properties you'd like to change:

const customTheme = {
  ...DarkTheme,
  colors: {
    ...DarkTheme.colors,
    primary: "255, 255, 0"
  }
};

Full Theme Schema

The PassportWidgetTheme object lets you customize the look and feel of the widget.

All fields are optional — if a value is not specified, the defaults from the selected base theme (DarkTheme or LightTheme) will be used.

export type PassportWidgetTheme = {
  colors?: {
    primary?: string;
    secondary?: string;
    background?: string;
    success?: string;
    failure?: string;
  };
  padding?: {
    widget?: {
      x?: string;
      y?: string;
    };
  };
  radius?: {
    widget?: string;
    button?: string;
  };
  transition?: {
    speed?: string;
  };
  font?: {
    family?: {
      body?: string;
      heading?: string;
      alt?: string;
    };
  };
  position?: {
    overlayZIndex?: string;
  };
};

Tips & Requirements

• colors.* must be defined using RGB format — for example: "255, 255, 0" (Hex codes and named colors are not supported)
• Font families must reference fonts that are already loaded on the page, except for the widget defaults
• overlayZIndex is only applied when collapseMode is set to overlay
• Use transition.speed to fine-tune widget animation timing (e.g. 0.2s, 0.5s)
• All values are optional — anything you omit will fall back to the base theme

Example

<PassportScoreWidget
  apiKey="<YOUR_API_KEY>"
  scorerId="<YOUR_SCORER_ID>"
  generateSignatureCallback={generateSignature}
  theme={{
    colors: { primary: "34, 197, 94", background: "255, 255, 255" },
    font: { family: { body: "Inter, sans-serif" } },
    radius: { widget: "12px", button: "8px" },
    transition: { speed: "0.2s" }
  }}
/>

Next Step

Once your theme is set, head over to the Component Reference to see all other available props.