Passport Embed -- Component Reference

This section is a technical reference for the PassportScoreWidget React component. It covers all configurable props, their types and meanings, as well as notes on component behavior and usage. Use this as a guide when integrating or troubleshooting the Passport Embed component in your codebase.

You will need to have a valid API key, Scorer ID, and to be granted access to Passport Embed by the Passport team (opens in a new tab) before you can use the component. You can get these by following the steps in our getting access guide.

Installing the Package

You can install the package using npm or yarn:

npm install @human-tech/passport-embed

or

yarn add @human-tech/passport-embed

Component Import

Make sure you have imported the component from the library:

import { PassportScoreWidget, DarkTheme, LightTheme } from "@human-tech/passport-embed";

Rendering the component

Once imported, you can render the PassportScoreWidget component anywhere in your React app where you want the verification UI to appear — for example, in a gated page, modal, or call-to-action section.

Here’s a basic example:

<PassportScoreWidget
  apiKey={PASSPORT_API_KEY}
  scorerId={PASSPORT_SCORER_ID}
  address={userAddress}
  generateSignatureCallback={signMessage}
  theme={DarkTheme}
/>

Props

The PassportScoreWidget accepts the following props:

Hooks

In addition to the main PassportScoreWidget component, the Passport Embed package provides a set of React hooks for developers who want to work with Passport scores programmatically, or build a custom verification UI.

usePassportScore

Fetches the user's Passport score and verification status for a given wallet address and Scorer ID.

Returns

Example

Here is an example of how to use the hook without making a request to the Passport API to confirm the score server-side (not recommended for protecting sensitive programs):

import { usePassportScore } from "@human-tech/passport-embed";
 
const { score, isPassing, loading, error } = usePassportScore({
  apiKey: PASSPORT_API_KEY,
  scorerId: PASSPORT_SCORER_ID,
  address: userAddress
});
 
if (loading) return <p>Loading score...</p>;
if (error) return <p>Error fetching score.</p>;
 
return (
  <div>
    <p>Your Passport score: {score}</p>
    {isPassing ? (
      <p>✅ You meet the threshold!</p>
    ) : (
      <p>⚠️ You don't meet the required score yet.</p>
    )}
  </div>
);

Please refer to our tutorial to see an example of how to use this hook with a request to the Passport API to confirm the score server-side (recommended for protecting sensitive programs).

Usage Example

Suppose we want to embed the widget in a page and allow it to handle wallet connection. We also want it to appear as a small badge that the user can expand. We might use the following props:

import { PassportScoreWidget, DarkTheme } from "@human-tech/passport-embed";
 
<PassportScoreWidget
  apiKey={API_KEY}
  scorerId={SCORER_ID}
  collapseMode="overlay"
  address={userAddress}
  generateSignatureCallback={signMessage}
  theme={DarkTheme}
/>

To review a more in-depth example, see our tutorial.

Component Behavior

• Initial State: The widget will detect if an address is provided. If not, it typically shows a prompt or button to connect a wallet (assuming connectWalletCallback is given). If an address is already provided, it will immediately attempt to fetch the Passport score for that address (calling generateSignatureCallback internally when needed).
• Loading & Error Handling: While the score is being fetched, the widget may show a loading indicator. If an error occurs (e.g., network issues or invalid API key), the widget will handle it by showing an error message in the UI (and you might see errors in the console for debugging). You don’t need to manually catch errors from the callbacks – the widget will display a user-friendly message (“Failed to load score,” etc.) if something goes wrong.
• Display of Score: Once retrieved, the widget will display a user's Stamp-based unique humanity score. A partner's score threshold can be set via the Developer Portal. This threshold will be used to identify if a user is passing or failing the verification.
• Verify additional stamps: If the user’s score is below the score threshold, the widget will guide them on next steps, which involves verifying additional stamps via the embed component. After the user verifies additional stamps, the widget will automatically update the score via the UI.
• Collapsing/Expanding: With collapseMode set to "shift" or "overlay", the widget will start in a minimized state – often an icon or small bar. When clicked, it expands to show the full details (score, message, etc.). If "off" is used, it’s always expanded. The expanded widget could be a panel that either pushes content (shift) or overlays above it. The user can likely collapse it back after viewing. This behavior allows the verification UI to stay out of the way until needed, which is especially useful on content-heavy pages.