UI Modal

Gateway Provider UI Modal

The GatewayProvider is a React component that enables your dApp frontend to:

  • access all available information of your user's Civic Pass

  • trigger the issuance and refresh of a new Civic Pass

1. Install the React component for your chain

Install the Civic Gateway library for your chain.

npm i @civic/solana-gateway-react@latest

Next, import and configure the GatewayProvider component.

The required configuration properties vary slightly depending on the chain. You can find the configuration properties of each chain here.

import { GatewayProvider } from "@civic/solana-gateway-react";
import { Connection, clusterApiUrl } from '@solana/web3.js';

<GatewayProvider
  connection={new Connection(clusterApiUrl("mainnet-beta"), "confirmed")}
  cluster="mainnet-beta"
  wallet={wallet}
  gatekeeperNetwork={gatekeeperNetwork}>
  {children}
</GatewayProvider>

Children wrapped by this GatewayProvider will have access to the connected wallet's Civic Pass.

We suggest placing the <GatewayProvider> as high up in the component tree as possible, to ensure you have access to the Civic Pass state throughout your dApp.

2. Use the useGateway hook to interact with a Civic Pass

You can also use the provided Identity Button reference implementation to handle everything described in this section.

Now that you have initialized the GatewayProvider context, you can use the included useGateway hook to:

  • trigger the issuance of a new Civic Pass modal

  • access the state of the Civic Pass

import { useGateway } from "@civic/solana-gateway-react";

Trigger the issuance of a Civic Pass

Calling the function requestGatewayToken opens the modal dialog, which guides the user through the flow of collecting and verifying their information. The information collected varies depending on the configured Gatekeeper Network. 

const { requestGatewayToken } = useGateway()

<button onclick={requestGatewayToken}>Civic Pass</button>

For example, this is the initial screen your users will see when issuing a Civic Liveness Pass:

Even if the user already has a Civic Pass, the modal supports being triggered for any possible pass status and will always display the correct screen that corresponds with that Civic Pass status.

If the the user already has a Civic Pass, triggering the modal again via requestGatewayToken displays the following screen:

Access the status of the Civic Pass

All children of the GatewayProvider have access to the user's Civic Pass status via the useGateway function. 

const { gatewayStatus, gatewayToken } = useGateway();

The gatewayStatus indicates the overall status of the Civic Pass and should be displayed in your dApp either via custom UI or by integrating the Civic Identity Button included with the library.

The gatewayToken represents the on-chain structure of the Civic Pass. This will is only defined if the Civic Pass is ACTIVE.

If the token does not exist or is in a inactive state (e.g. frozen), this variable will be undefined. The dApp should disable certain parts of the UI when gatewayToken is undefined to prevent dApp usage. This only complements the on-chain check and does not replace it.

3. Edit the Pass Status UI (optional)

To expose the status of the user's Civic Pass in your UI, add the Identity Button component (also included in the Gateway library), by placing it inside the <GatewayProvider> context you created in the previous step.

import IdentityButton from '@civic/solana-gateway-react';
...
<IdentityButton />

Beyond just displaying the Civic Pass status, users can also start the issuance of their Pass if they do not already have one. The Pass Status UI will update to display the correct Civic Pass status.

You can find more details on the Pass Status UI here.

PreviousUI IntegrationNextConfiguration Parameters

Last updated