@passageidentity/passage-react v0.9.4

About

Passage by 1Password unlocks the passwordless future with a simpler, more secure passkey authentication experience. Passage handles the complexities of the WebAuthn API, and allows you to implement passkeys with ease.

Use Passkey Flex to add passkeys to an existing authentication experience.

Use Passkey Complete as a standalone passwordless auth solution.

Use Passkey Ready to determine if your users are ready for passkeys.

In passage-react

Passage-React the easiest way to use Passage Passkey Complete in your React application. Passage-React provides native react integration with the Passage elements, modular components that provides complete UI/UX for modern authentication, embedded directly into your website.

What's Included?

🙆 User login, registration, and profile cross-platform elements.

🎨 Complete UI/UX for all device types and auth flows – in other words, it just works.

🔒 Full passkey authentication.

✨ Magic Link and One-Time Passcodes over email or SMS.

👥 Authentication with Social providers.

Product	Compatible
Passkey Flex	✖️ For Passkey Flex, check out passage-flex-js
Passkey Complete	✅
Passkey Ready	✖️ For Passkey Ready, check out Authentikit

Getting Started

Check Prerequisites

Install

npm i @passageidentity/passage-react

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 (
        <>
            <PassageAuth />
        </>
    );
};

Support & Feedback

We are here to help! Find additional docs, the best ways to get in touch with our team, and more within our support resources.

API Reference

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

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

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

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

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

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

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

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

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

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

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

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.

UsePassageHookProps

Returns

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