Building a React App with Biometric Authentication

Chris Loper
February 14, 2022

Passage offers developers a frictionless process to implement passwordless user authentication into their application. In this guide, learn how to build a simple React application that uses Passage for biometric authentication.

Users will log in to your application using the biometrics built into their devices (e.g. FaceID, TouchID, Windows Hello, etc) or with magic links sent to their email. The app will be built such that authenticated users can view a simple dashboard, while unauthenticated users will be blocked. This article will walk you through how to create a React app, setup the components, and authenticate users with Passage.

If you are already familiar with React, you can go straight to our full example application on GitHub or skip to the "Add User Authentication with Passage" section to learn how to integrate biometric authentication into an existing application.


You will need to have Node >= 14.0.0 and npm >= 5.6 on your machine. To create a React app run:

Now install the router (react-router-dom):

Build Views for the Application

The router is used to navigate between the views in your application. In this application, we will have two views Home.js and Dashboard.js. The Home view will contain Passage’s <passage-auth> custom element, which enables user authentication. The Dashboard view will be an authenticated route and will block any unauthenticated users from viewing the dashboard.

Lets start with building the Home view src/views/Home.js:

Now we will build a simple Dashboard view src/views/Dashboard.js:

Setup the Router in app.js and index.js

Let’s edit src/app.js, which is the entry point for the React app. Configure the router to have routes to both the Home view and the Dashboard view:

Also, edit src/index.js to add the router to the application:

Now let’s create a Banner component that we can add to src/app.js, making it visible throughout the application. Let’s create a component directory and create the banner.js file. Also, let's create a styles directory and create a Banner.module.css file to add CSS styling to the Banner component.

Let's build src/components/banner.js with this code:

Copy this CSS into src/styles/Banner.module.css to add styling to the above component:

Now let’s add the Banner component to src/app.js so that it will appear throughout the app:

Now lets add a footer and some styling to src/app.js:

And the styling lives in src/styles/App.module.css

Add User Authentication with Passage

Now it is time to add passwordless authentication to your application using Passage. First, install the Passage custom element from npm:

Then import the package in the view where you intend to authenticate users. In this case, src/views/Home.js

Importing this script will register the Passage custom element for use in your React view. For more information about custom elements refer to the online documentation.

Create an application in the Passage Console (here) with the following settings:

  • Authentication Origin: http://localhost:3000
  • Redirect URL: /dashboard

Below is a screenshot from creating a Passage App in the Passage Console:

Once the application has been created, copy the Application ID from the console into a .env file in the root of React app’s repository.

Now lets add the passage-auth custom element to src/views/Home.js

Verifying User Authentication

Now it is time to prevent unauthenticated users from accessing the dashboard page. Please keep in mind that this dashboard protection will not protect sensitive API endpoints. Your server should always use one of the Passage backend libraries to authorize users before returning sensitive data.

For the simplicity of this example, let’s focus on the frontend code.

Instead, implement this check by creating a hook to authenticate the current Passage user. This hook contains a reusable piece of stateful logic that allows any component to check if the current user is authenticated and return basic user info that Passage stores for you.

Create a directory for hooks and create a file called useCurrentUser.js:

The code for this hook is as follows:

Note: The React useEffect() hook happens on both mount and unmount, so canceling the API request will prevent an error that can occur when handling API requests in a useEffect hook that occurs when setting the state on a component that is unmounted.

Now that this hook has been implemented, move back to src/view/Dashboard.js and use this hook to verify that a user has been properly authenticated.

Now unauthenticated users that visit /dashboard will be shown an unauthorized page, while authenticated user will be shown their username.

Note: Notice that styles have also been added to this version of src/views/Dashboard.js A copy of src/styles/Dashboard.module.css can be found below:

Now run the app, to see Passage biometric authentication in action:


Congratulations! You now have a React application that utilizes passwordless authentication. Biometric authentication, as you hopefully can see, is both frictionless to implement with Passage and effortless for end users to authenticate themselves.

You can see the finished application on GitHub here.

Learn More About Passage

To learn more about Passage and biometric authentication for web applications, you can:

  • Explore our dashboard to view and create users, customize your application, and add friends
  • Read our guides for other tech stacks and learn how to authorize requests in your backend server
  • Join our Discord and say hi

‍Passage is in beta and actively seeking feedback on the product. If you have feedback, bug reports, or feature requests, we would love to hear from you. You can email us at or fill out this form.