❤
npm
Sign UpSign In

@passageidentity/passage-react
TypeScript icon, indicating that this package has built-in type declarations

0.8.10 • Public • Published

Passage logo

npm version

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:

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;
}

Readme

Keywords

none

Package Sidebar

Install

npm i @passageidentity/passage-react

Weekly Downloads

10

Version

0.8.10

License

none

Unpacked Size

387 kB

Total Files

40

Last publish

Collaborators

  • jennmacfarlane
  • passageamy
  • rickypadilla
  • passenger_mac
  • passage-blayne
  • kevinflanagan
  • colehecht
  • apobletts
Try on RunKit
Report malware