React Frontend Integration

For the full React Library Reference, click here.

​

Quick example

The following example will display a different message for logged-in users vs logged out. We’ll go into more detail about how it works and show more advanced examples below.

import { AuthProvider, withAuthInfo } from "@propelauth/react";

const App = withAuthInfo((props) => {
  // isLoggedIn and user are injected automatically from withAuthInfo
  if (props.isLoggedIn) {
    return <div>You are logged in as {props.user.email}</div>;
  } else {
    return <div>You are not logged in</div>;
  }
});

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(
  <React.StrictMode>
    <AuthProvider authUrl={process.env.REACT_APP_AUTH_URL}> 
      <App />
    </AuthProvider>
  </React.StrictMode>
);

Your auth URL can be found in your PropelAuth dashboard. We are using an ENV variable because you will have a different URL for your test and production environment.

​

How it works

For a detailed description of what’s going on under the hood, see here.

​

Configure your project

Go to your PropelAuth project and click Frontend Integration in the sidebar. You will see:

• Port - The port your app runs on locally. The default for React is 3000. After entering 3000, your test environment will allow requests from http://localhost:3000.
• Login Redirect Path - After a user logs in, they will be redirected here. For example,/ will redirect them to http://localhost:3000/.
• Logout Redirect Path - After a user logs out, they will be redirected here.
• Auth URL - This is where your authentication pages are hosted, and you will need this for the setup step.

​

Installation

In your React app, install the @propelauth/react library.

$ npm install --save @propelauth/react

​

Set up AuthProvider

AuthProvider is the provider of a React context that manages the current user’s access token and metadata. You cannot use the other hooks without it. AuthProvider manages authentication information and all other components fetches from it.

It is recommended to put the AuthProvider context at the top level of your application, so it never unmounts.

import { AuthProvider } from "@propelauth/react";

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(
  <AuthProvider authUrl={process.env.REACT_APP_AUTH_URL}> 
    <YourApp />
  </AuthProvider>,
  document.getElementById("root")
);

The authUrl is the base URL where your authentication pages are hosted. You can find this under the Frontend Integration section for your project.

​

RequiredAuthProvider

If your entire application requires a user to be logged in, you can instead use RequiredAuthProvider.

import { RequiredAuthProvider, RedirectToLogin } from "@propelauth/react";

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(
  <RequiredAuthProvider
    authUrl={process.env.REACT_APP_AUTH_URL}
    displayWhileLoading={<Loading />}
    displayIfLoggedOut={<RedirectToLogin />}
  >
    <YourApp />
  </RequiredAuthProvider>,
  document.getElementById("root")
);

RequiredAuthProvider has two additional props:

1. displayWhileLoading: A React element to display while the AuthProvider is fetching auth information. Defaults to an empty element
2. displayIfLoggedOut: A React eleent to display if the current user is logged out. Defaults to RedirectToLogin

​

Get current user information

There are three options for getting the current user’s information.

​

withAuthInfo

withAuthInfo wraps a component and automatically adds auth information to the props of the component.

withAuthInfo(Component, {
  // A React element to display while the AuthProvider is fetching auth information. Defaults to an empty element
  displayWhileLoading: <div>Loading...</div>,
});

The following props are injected to the underlying component:

​

withRequiredAuthInfo

This is identical to withAuthInfo, except Component is only rendered if the user is logged in. You are guaranteed that isLoggedIn is true and the accessToken is not null.

withRequiredAuthInfo(Component, {
  // A React element to display while the AuthProvider is fetching auth information. Defaults to an empty element
  displayWhileLoading: <div>Loading...</div>,
  // A React element to display if the current user is logged out. Defaults to <RedirectToLogin />
  displayIfLoggedOut: <div>You are logged out</div>,
});

​

useAuthInfo

import { useAuthInfo } from "@propelauth/react";

function MinimalExample() {
  const authInfo = useAuthInfo();

  // Unlike the higher order functions, we need to check the loading case now
  if (authInfo.loading) {
    return <div>Loading...</div>;
  } else if (authInfo.isLoggedIn) {
    return <div>You are logged in as {props.user.email}</div>;
  } else {
    return <div>You are not logged in</div>;
  }
}

export default MinimalExample;

A React hook which gets auth information. authInfo contains:

​

Other utilities

• useLogoutFunction - Returns a function for logging out the current user.

• useRedirectFunctions - Returns a set of functions to redirect the user to different pages (e.g. signup, login).

For a complete list of utilities, see the React Library Reference.

​

Organizations

The orgHelper, provided by withAuthInfo, withRequiredAuthInfo, or useAuthInfo, helps manage the current user’s organization information with ease. It’s an object which has the following functions (types included):

type OrgHelper = {
    // returns all orgs that the user is a member of
    getOrgs: () => OrgMemberInfo[],
    // returns all org ids that the user is a member of
    getOrgIds: () => string[],
    // returns org information for a given orgId
    getOrg: (orgId: string) => OrgMemberInfo | undefined,
    // returns org information for a given org by name
    getOrgByName: (orgName: string) => OrgMemberInfo | undefined,
}

type OrgMemberInfo = {
    orgId: string,
    orgName: string,
    urlSafeOrgName: string
    // The role of the user within this organization
    userAssignedRole: string
    userPermissions: string[]
}

​

Roles and Permissions

Your users will have a role in an organization. By default, these roles are Owner, Admin, and Member - but you can configure them. Each role can have permissions associated with them. See roles and permissions for more details.

The accessHelper, provided by withAuthInfo, withRequiredAuthInfo, or useAuthInfo, helps check the current user’s role and permission(s) within a specific organization.

type AccessHelper = {
    isRole: (orgId: string, role: string) => boolean
    isAtLeastRole: (orgId: string, role: string) => boolean
    hasPermission: (orgId: string, permission: string) => boolean
    hasAllPermissions: (orgId: string, permissions: string[]) => boolean
}

​

Active Organization

Since users can be in more than one organization, one common use case is to pick a single organization that your user is currently operating within.

Commonly, developers use localStorage, a path parameter, or subdomain (e.g. https://CUSTOMER.yourproduct.com or https://app.yourproduct.com/CUSTOMER) to indicate which organization the user is currently operating within.

The AuthProvider and RequiredAuthProvider optionally take in a getActiveOrgFn which enables you to select the currently active organization, like so:

// Get the active org from a path parameter grabbed from our router
<AuthProvider authUrl={AUTH_URL} getActiveOrgFn={() => router.query.orgName}>

useActiveOrg allows you to fetch the active organization later on. It will also verify that the current user is actually in that organization.

function OrgName() {
  const org = useActiveOrg();
  return <div>{org.orgName}</div>;
}

​

Making an authenticated HTTP request

For authenticated requests on behalf of your user, you must provide an access token. There are many of ways to make HTTP requests in Javascript. You could use the Fetch API, XMLHttpRequest, or a library like axios.

Just like isLoggedIn and user, the access token is available from withAuthInfo, withRequiredAuthInfo, or useAuthInfo. You provide it in the request in the Authorization header, like so:

Authorization: Bearer YOUR_ACCESS_TOKEN

Code sample of the Authorization with the Fetch API:

function whoAmI(accessToken) {
  return fetch("/whoami", {
    method: "GET",
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
}

​

Examples

For detailed examples, please see React Library Reference Examples.

​

Next Steps

Done with your frontend? Next you can integrate your backend.