passage-react

Getting Started

Installation

Using npm

npm install @passageidentity/passage-react

Configure Passage

Create a new Passage App

To create an app, first login or create an account for the Passage Console at https://console.passage.id/register.

When you first sign up, you will be redirected to your homepage that includes an example application to explore.

To create your first new application, select the "Create New App" button on the home page.

Give your application a name and then provide the following fields:

• Authentication Origin - the domain that Passage will run on
• Redirect URL - the path you want to direct users to after successful login

For example, if you are building a local test app, your settings will probably look something like this:

• Authentication Origin - http://localhost:8080
• Redirect URL - /

Once you've created your application, copy the Application ID from the dashboard.

For more information visit https://docs.passage.id/getting-started/creating-a-new-app

Configure passage-react in your React application

Configure passage-react by wrapping your application with a PassageProvider

1. Import the PassageProvider
2. Wrap your application code with the PassageProvider
   • Pass your Passage app id to the PassageProvider

// src/index.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

// Import the PassageProvider
import { PassageProvider } from '@passageidentity/passage-react';

ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
    <React.StrictMode>
        // Wrap your application code with PassageProvider // providing your Passage app id
        <PassageProvider appId='YOUR_PASSAGE_APP_ID'>
            <App />
        </PassageProvider>
    </React.StrictMode>,
);

Add a login or register component

In your application use one of the Passage Authentication components to display a login form for your users.

// src/login.tsx
import React from 'react';
import { PassageAuth } from '@passageidentity/passage-react';

export const LoginPage: React.FC = () => {
    return (
        <>
            <h1>Example Login Page</h1>
            <PassageAuth />
        </>
    );
};

Components

Configuration Components

PassageProvider

The PassageProvider component wraps your application to provide the configuration for other Passage Components.

// Import the PassageProvider
import { PassageProvider } from '@passageidentity/passage-react';

<PassageProvider appId='YOUR_PASSAGE_APP_ID'>
    <App />
</PassageProvider>;

Props

| Name | Required | Type | Description | | :----------------- | :------: | :----: | ---------------------------: | | appId | Yes | string | Your Passage app id. | | defaultCountryCode | No | string | ISO Country code | | lang | No | string | Default language | | theme (deprecated) | No | PassageThemeProps | Passage Theme, theme is deprecated, use the new lightTheme and darkTheme properties instead. Theme will apply a light theme.| | lightTheme | No | PassageThemeProps | Passage Theme | | darkTheme | No | PassageThemeProps | Passage Theme |

Authentication/Registration Components

PassageAuth

Renders the passage-auth element.

// src/login.tsx
import React from 'react';
import { PassageAuth } from '@passageidentity/passage-react';

export const AuthPage: React.FC = () => {
    return (
        <>
            <h1>Example Login or Register Page</h1>
            <PassageAuth />
        </>
    );
};

Props

| Name | Required | Type | Description | | :----------------- | :------: | :---------------------------------------: | ---------------------------------------: | | appId | No* | string | Your Passage app id. | | defaultCountryCode | No* | string | ISO Country code | | lang | No* | string | Default language | | beforeAuth | No | BeforeAuthCallback | Method to call before authentication | | onSuccess | No | OnSuccessCallback | Method to call on authentication success | | tokenStore | No | TokenStore | Custom token store instance | | theme | No | "light", "dark", "auto" | Use a light, dark, or auto theme |

Note: If not using the PassageProvider the appId property is required. If using the PassageProvider appId, defaultCountryCode, and lang props will be loaded from the PassageProvider but if passed in will override the values for this component instance only.

PassageRegister

Renders the passage-register element.

// src/login.tsx
import React from 'react';
import { PassageRegister } from '@passageidentity/passage-react';

export const RegisterPage: React.FC = () => {
    return (
        <>
            <h1>Example Register Page</h1>
            <PassageRegister />
        </>
    );
};

Props

| Name | Required | Type | Description | | :----------------- | :------: | :---------------------------------------: | ---------------------------------------: | | appId | No* | string | Your Passage app id. | | defaultCountryCode | No* | string | ISO Country code | | lang | No* | string | Default language | | beforeAuth | No | BeforeAuthCallback| Method to call before authentication | | onSuccess | No | OnSuccessCallback | Method to call on authentication success | | tokenStore | No | TokenStore | Custom token store instance | | theme | No | "light", "dark", "auto" | Use a light, dark, or auto theme |

Note: If not using the PassageProvider the appId property is required. If using the PassageProvider appId, defaultCountryCode, and lang props will be loaded from the PassageProvider but if passed in will override the values for this component instance only.

PassageLogin

Renders the passage-login element.

// src/login.tsx
import React from 'react';
import { PassageLogin } from '@passageidentity/passage-react';

export const LoginPage: React.FC = () => {
    return (
        <>
            <h1>Example Login Page</h1>
            <PassageLogin />
        </>
    );
};

Props

| Name | Required | Type | Description | | :----------------- | :------: | :---------------------------------------: | ---------------------------------------: | | appId | No* | string | Your Passage app id. | | defaultCountryCode | No* | string | ISO Country code | | lang | No* | string | Default language | | beforeAuth | No | BeforeAuthCallback | Method to call before authentication | | onSuccess | No | OnSuccessCallback | Method to call on authentication success | | tokenStore | No | TokenStore | Custom token store instance | | theme | No | "light", "dark", "auto" | Use a light, dark, or auto theme |

Note: If not using the PassageProvider the appId property is required. If using the PassageProvider appId, defaultCountryCode, and lang props will be loaded from the PassageProvider but if passed in will override the values for this component instance only.

User Components

PassageProfile

Renders the passage-profile element.

// src/login.tsx
import React from 'react';
import { PassageProfile } from '@passageidentity/passage-react';

export const ProfilePage: React.FC = () => {
    return (
        <>
            <h1>Example Profile Page</h1>
            <PassageProfile />
        </>
    );
};

Props

| Name | Required | Type | Description | | :----------------- | :------: | :----: | ---------------------------: | | appId | No* | string | Your Passage app id. | | defaultCountryCode | No* | string | ISO Country code | | lang | No* | string | Default language | | tokenStore | No | TokenStore | Custom token store instance | | theme | No | "light", "dark", "auto" | Use a light, dark, or auto theme |

Note: If not using the PassageProvider the appId property is required. If using the PassageProvider appId, defaultCountryCode, and lang props will be loaded from the PassageProvider but if passed in will override the values for this component instance only.

PassagePasskeyTable

Renders the passage-passkey-table element.

// src/login.tsx
import React from 'react';
import { PassagePasskeyTable } from '@passageidentity/passage-react';

export const PasskeyTablePage: React.FC = () => {
    return (
        <>
            <h1>Example Passkey Table Page</h1>
            <PassagePasskeyTable />
        </>
    );
};

Props

| Name | Required | Type | Description | | :----------------- | :------: | :----: | ---------------------------: | | appId | No* | string | Your Passage app id. | | defaultCountryCode | No* | string | ISO Country code | | lang | No* | string | Default language | | tokenStore | No | TokenStore | Custom token store instance | | theme | No | "light", "dark", "auto" | Use a light, dark, or auto theme |

Note: If not using the PassageProvider the appId property is required. If using the PassageProvider appId, defaultCountryCode, and lang props will be loaded from the PassageProvider but if passed in will override the values for this component instance only.

Guard Components

PassageAuthGuard

Protects content by requiring a logged in user to view the content.

A component can be passed in which will render when the user has not been authenticated. The default is to render null.

// src/login.tsx
import React from 'react';
import { PassageAuthGuard } from '@passageidentity/passage-react';

export const ProtectedPage: React.FC = () => {
    return (
        <PassageAuthGuard>
            <p>Protected content</p>
        </PassageAuthGuard>
    );
};

Props

| Name | Required | Type | Description | | :--------- | :------: | :-------------: | ---------------------------------------------------: | | unAuthComp | No | React.ReactNode | Component to render if the user is not authenticated |

PassageUnAuthGuard

The opposite of PassageAuthGuard ensures a user is NOT authenticated to view the content.

A component can be passed in which will render when the user is authenticated. The default is to render null.

// src/login.tsx
import React from 'react';
import { PassageUnAuthGuard } from '@passageidentity/passage-react';

export const UnAuthOnlyPage: React.FC = () => {
    return (
        <PassageUnAuthGuard>
            <p>Protected content</p>
        </PassageUnAuthGuard>
    );
};

Props

| Name | Required | Type | Description | | :------- | :------: | :-------------: | -----------------------------------------------: | | authComp | No | React.ReactNode | Component to render if the user is authenticated |

Styling Components

PassageTheme (Deprecated)

Note: PassageTheme has been deprecated. Use the PassageLightTheme or PassageDarkTheme components instead. PassageTheme will now apply a Light theme.

The PassageTheme component can customize the look and feel of the Passage Element to match your brand.

// src/login.tsx
import React from 'react';
import { PassageAuth, PassageTheme } from '@passageidentity/passage-react';

export const RegisterPage: React.FC = () => {
    return (
        <>
            <h1>Example Register Page</h1>
            <PassageTheme primaryColor="#ff0000">
                <PassageRegister />
            </PassageTheme>
        </>
    );
};

Props

| Name | Required | Type | Default Value | | :------- | :------: | :-------------: | -----------------------------------------------: | | bodyFontFamily | No | string | 'Helvetica', BlinkMacSystemFont, -apple-system, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', 'Helvetica', 'Arial', sans-serif | | headerFontFamily | No | string | 'Helvetica', BlinkMacSystemFont, -apple-system, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', 'Helvetica', 'Arial', sans-serif | | containerBackgroundColor | No | string | #fff | | containerMaxWidth | No | string | 300px | | containerMargin | No | string | auto | | containerPadding | No | string | 30px 30px 20px | | errorColor | No | string | #dd0031 | | bodyFontSize | No | string | 14px | | bodyFontWeight | No | string | 400 | | bodyTextColor | No | string | #000 | | headerFontSize | No | string | 24px | | headerFontWeight | No | string | 700 | | headerTextColor | No | string | #000 | | anchorTextColor | No | string | #000 | | anchorHoverColor | No | string | #4d4d4d | | anchorActiveColor | No | string | #6b6b6b | | otpInputBackgroundColor | No | string | #fff | | inputTextColor | No | string | #000 | | inputBoxBackgroundColor | No | string | #fff | | inputBoxBorderRadius | No | string | 5px | | checkboxBackgroundColor | No | string | #000 | | checkboxTextColor | No | string | #fff | | controlBorderRadius | No | string | 5px | | controlBorderColor | No | string | #d7d7d7 | | controlBorderActiveColor | No | string | #000 | | buttonFontSize | No | string | 16px | | buttonFontWeight | No | string | 400 | | buttonWidth | No | string | 50% | | primaryButtonBackgroundColor | No | string | #000 | | primaryButtonTextColor | No | string | #fff | | primaryButtonBorderRadius | No | string | 5px | | primaryButtonBorderColor | No | string | #000 | | primaryButtonBorderWidth | No | string | 0px | | primaryButtonBorderHoverColor | No | string | #000 | | primaryButtonTextHoverColor | No | string | #fff | | primaryButtonBackgroundHoverColor | No | string | #4d4d4d | | primaryButtonTextActiveColor | No | string | #fff | | primaryButtonBackgroundActiveColor | No | string | #6b6b6b | | primaryButtonBorderActiveColor | No | string | #000 | | secondaryButtonBackgroundColor | No | string | #fff | | secondaryButtonTextColor | No | string | #000 | | secondaryButtonBorderRadius | No | string | 5px | | secondaryButtonBorderColor | No | string | #000 | | secondaryButtonBorderWidth | No | string | #000 | | secondaryButtonBorderHoverColor | No | string | #4d4d4d | | secondaryButtonTextHoverColor | No | string | #000 | | secondaryButtonBackgroundHoverColor | No | string | #d7d7d7 | | secondaryButtonTextActiveColor | No | string | #000 | | secondaryButtonBackgroundActiveColor | No | string | #e0e0e0 | | secondaryButtonBorderActiveColor | No | string | #6b6b6b | | tableHeaderBorderColor | No | string | #d7d7d7 | | tableRowBorderColor | No | string | #e8e8e8 | | tablePaginatorSelectedColor | No | string | #d7d7d7 | | tablePaginatorHoverColor | No | string | #e8e8e8 | | tableDeviceInfoColorDefault | No | string | #6b6b6b | | tableDeviceIconColorDefault | No | string | #6b6b6b | | tableActionIconHoverColorDefault | No | string | #6b6b6b |

PassageLightTheme

The PassageTheme component can customize the look and feel of the Passage Element to match your brand.

// src/login.tsx
import React from 'react';
import { PassageAuth, PassageTheme } from '@passageidentity/passage-react';

export const RegisterPage: React.FC = () => {
    return (
        <>
            <h1>Example Register Page</h1>
            <PassageTheme primaryColor="#ff0000" />
            <PassageRegister />
        </>
    );
};

Props

| Name | Required | Type | Default Value | | :------- | :------: | :-------------: | -----------------------------------------------: | | bodyFontFamily | No | string | 'Helvetica', BlinkMacSystemFont, -apple-system, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', 'Helvetica', 'Arial', sans-serif | | headerFontFamily | No | string | 'Helvetica', BlinkMacSystemFont, -apple-system, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', 'Helvetica', 'Arial', sans-serif | | containerBackgroundColor | No | string | #fff | | containerMaxWidth | No | string | 300px | | containerMargin | No | string | auto | | containerPadding | No | string | 30px 30px 20px | | errorColor | No | string | #dd0031 | | bodyFontSize | No | string | 14px | | bodyFontWeight | No | string | 400 | | bodyTextColor | No | string | #000 | | headerFontSize | No | string | 24px | | headerFontWeight | No | string | 700 | | headerTextColor | No | string | #000 | | anchorTextColor | No | string | #000 | | anchorHoverColor | No | string | #4d4d4d | | anchorActiveColor | No | string | #6b6b6b | | otpInputBackgroundColor | No | string | #d7d7d7 | | inputTextColor | No | string | #000 | | inputBoxBackgroundColor | No | string | #fff | | inputBoxBorderRadius | No | string | 5px | | checkboxBackgroundColor | No | string | #000 | | checkboxTextColor | No | string | #fff | | controlBorderRadius | No | string | 5px | | controlBorderColor | No | string | #d7d7d7 | | controlBorderActiveColor | No | string | #000 | | buttonFontSize | No | string | 16px | | buttonFontWeight | No | string | 400 | | buttonWidth | No | string | 50% | | primaryButtonBackgroundColor | No | string | #000 | | primaryButtonTextColor | No | string | #fff | | primaryButtonBorderRadius | No | string | 5px | | primaryButtonBorderColor | No | string | #000 | | primaryButtonBorderWidth | No | string | 0px | | primaryButtonBorderHoverColor | No | string | #000 | | primaryButtonTextHoverColor | No | string | #fff | | primaryButtonBackgroundHoverColor | No | string | #4d4d4d | | primaryButtonTextActiveColor | No | string | #fff | | primaryButtonBackgroundActiveColor | No | string | #6b6b6b | | primaryButtonBorderActiveColor | No | string | #000 | | secondaryButtonBackgroundColor | No | string | #fff | | secondaryButtonTextColor | No | string | #000 | | secondaryButtonBorderRadius | No | string | 5px | | secondaryButtonBorderColor | No | string | #000 | | secondaryButtonBorderWidth | No | string | #000 | | secondaryButtonBorderHoverColor | No | string | #4d4d4d | | secondaryButtonTextHoverColor | No | string | #000 | | secondaryButtonBackgroundHoverColor | No | string | #d7d7d7 | | secondaryButtonTextActiveColor | No | string | #000 | | secondaryButtonBackgroundActiveColor | No | string | #e0e0e0 | | secondaryButtonBorderActiveColor | No | string | #6b6b6b | | tableHeaderBorderColor | No | string | #d7d7d7 | | tableRowHoverColor | No | string | #e0e0e0 | | tableRowBorderColor | No | string | #e8e8e8 | | tablePaginatorSelectedColor | No | string | #d7d7d7 | | tablePaginatorHoverColor | No | string | #e8e8e8 |

PassageDarkTheme

The PassageTheme component can customize the look and feel of the Passage Element to match your brand.

// src/login.tsx
import React from 'react';
import { PassageAuth, PassageTheme } from '@passageidentity/passage-react';

export const RegisterPage: React.FC = () => {
    return (
        <>
            <h1>Example Register Page</h1>
            <PassageTheme primaryColor="#ff0000" />
            <PassageRegister />
        </>
    );
};

Props

| Name | Required | Type | Default Value | | :------- | :------: | :-------------: | -----------------------------------------------: | | bodyFontFamily | No | string | 'Helvetica', BlinkMacSystemFont, -apple-system, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', 'Helvetica', 'Arial', sans-serif | | headerFontFamily | No | string | 'Helvetica', BlinkMacSystemFont, -apple-system, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', 'Helvetica', 'Arial', sans-serif | | containerBackgroundColor | No | string | #fff | | containerMaxWidth | No | string | 300px | | containerMargin | No | string | auto | | containerPadding | No | string | 30px 30px 20px | | errorColor | No | string | #dd0031 | | bodyFontSize | No | string | 14px | | bodyFontWeight | No | string | 400 | | bodyTextColor | No | string | #000 | | headerFontSize | No | string | 24px | | headerFontWeight | No | string | 700 | | headerTextColor | No | string | #000 | | anchorTextColor | No | string | #000 | | anchorHoverColor | No | string | #4d4d4d | | anchorActiveColor | No | string | #6b6b6b | | otpInputBackgroundColor | No | string | #d7d7d7 | | inputTextColor | No | string | #000 | | inputBoxBackgroundColor | No | string | #fff | | inputBoxBorderRadius | No | string | 5px | | checkboxBackgroundColor | No | string | #000 | | checkboxTextColor | No | string | #fff | | controlBorderRadius | No | string | 5px | | controlBorderColor | No | string | #d7d7d7 | | controlBorderActiveColor | No | string | #000 | | buttonFontSize | No | string | 16px | | buttonFontWeight | No | string | 400 | | buttonWidth | No | string | 50% | | primaryButtonBackgroundColor | No | string | #000 | | primaryButtonTextColor | No | string | #fff | | primaryButtonBorderRadius | No | string | 5px | | primaryButtonBorderColor | No | string | #000 | | primaryButtonBorderWidth | No | string | 0px | | primaryButtonBorderHoverColor | No | string | #000 | | primaryButtonTextHoverColor | No | string | #fff | | primaryButtonBackgroundHoverColor | No | string | #4d4d4d | | primaryButtonTextActiveColor | No | string | #fff | | primaryButtonBackgroundActiveColor | No | string | #6b6b6b | | primaryButtonBorderActiveColor | No | string | #000 | | secondaryButtonBackgroundColor | No | string | #fff | | secondaryButtonTextColor | No | string | #000 | | secondaryButtonBorderRadius | No | string | 5px | | secondaryButtonBorderColor | No | string | #000 | | secondaryButtonBorderWidth | No | string | #000 | | secondaryButtonBorderHoverColor | No | string | #4d4d4d | | secondaryButtonTextHoverColor | No | string | #000 | | secondaryButtonBackgroundHoverColor | No | string | #d7d7d7 | | secondaryButtonTextActiveColor | No | string | #000 | | secondaryButtonBackgroundActiveColor | No | string | #e0e0e0 | | secondaryButtonBorderActiveColor | No | string | #6b6b6b | | tableHeaderBorderColor | No | string | #d7d7d7 | | tableRowHoverColor | No | string | #e0e0e0 | | tableRowBorderColor | No | string | #e8e8e8 | | tablePaginatorSelectedColor | No | string | #d7d7d7 | | tablePaginatorHoverColor | No | string | #e8e8e8 |

Hooks

usePassage

Provides access to the Passage configuration, an instance of passage.js and other Passage functionality.

import { usePassageJS } from '@passageidentity/passage-react';
import { Passage, Session, User } from '@passageidentity/passage-js';

const MyComponent = () => {

    // if using PassageProvider
    const { passageInstance, currentSession, currentUser, appId, lang, defaultCountryCode } =
        usePassageJS();

    // if not useing PassageProvider
    const { passageInstance, currentSession, currentUser, appId, lang, defaultCountryCode } =
        usePassageJS({ appId: 'YOUR_PASSAGE_APP_ID', lang: 'en'', defaultCountryCode: 'us'});

    // other code using data or methods provided by usePassage
};

Parameters

If using the PassageProvider to wrap your app, then you do not need to pass any parameters, unless you want to override a setting for this hook instance only.

| Name | Required | Type | Description | | :----------------- | :------: | :----: | ---------------------------: | | props | No | UsePassageHookProps | Passage Configuration |

UsePassageHookProps

| Name | Required | Type | Description | | :----------------- | :------: | :----: | ---------------------------: | | appId | No | string | Your Passage app id. | | defaultCountryCode | No | string | ISO Country code | | lang | No | string | Default language | | tokenStore | No | TokenStore | Custom token store instance |

Returns

| Name | Type | Description | | :----------------- | :-------------------------------------------------------: | -----------------------------------------------------: | | appId | string | Your Passage app id. | | defaultCountryCode | string | ISO Country code | | lang | string | Default language | | passageInstance | passage.js | Instance of Passage | | getCurrentSession | GetCurrentSessionFn | The current users Passage Session | | getCurrentUser | GetCurrentUserFn | The current user | | signOut | PassageSignOutFn | Method than can be called to sign out the current user |

Types

BeforeAuthCallback

type BeforeAuthCallback = (email: string) => boolean;

OnSuccessCallback

type OnSuccessCallback = (authResult: authResult) => void;

TokenStore

Learn how to create a custom token store here.

type TokenStore = () => TokenStore;

PassageSignOutFn

type PassageSignOutFn = () => Promise<boolean>;

GetCurrentUserFn

type GetCurrentUserFn = () => User | undefined;

GetCurrentSessionFn

type GetCurrentSessionFn = () => Session | undefined;

PassageThemeProps

interface PassageThemeProps {
    primaryColor?: string;
    containerBackground?: string;
    containerBackgroundColor?: string;
    containerMaxWidth?: string;
    containerMargin?: string;
    containerPadding?: string;
    errorColor?: string;
    bodyFontFamily?: string;
    bodyFontSize?: string;
    bodyFontWeight?: string;
    bodyTextColor?: string;
    headerFontFamily?: string;
    headerFontSize?: string;
    headerFontWeight?: string;
    headerTextColor?: string;
    butonFontSize?: string;
    buttonFontWeight?: string;
    buttonWidth?: string;
    buttonBorderRadius?: string;
    onprimaryColor?: string;
    onHoverColor?: string;
    hoverColor?: string;
    onactiveColor?: string;
    activeColor?: string;
    controlBorderRadius?: string;
    controlBorderColor?: string;
    tableHeaderBorderColor?: string;
    tableRowBorderColor?: string;
    tablePaginatorSelectedColor?: string;
    tablePaginatorHoverColor?: string;
    tableRowBorderColor?: string;
    tablePaginatorSelectedColor?: string;
    tablePaginatorHoverColor?: string;
}