FusionAuth React SDK

This SDK allows you to add login, logout, and registration buttons to your React application. You can do this via pre-built buttons, hooks, or higher-order components.

Your users will be sent to FusionAuth’s themeable hosted login pages and then log in. After that, they are sent back to your React application.

Once authentication succeeds, the following secure, HTTP-only cookies will be set:

  • app.at - an OAuth Access Token

  • app.rt - a Refresh Token used to obtain a new app.at. This cookie will only be set if refresh tokens are enabled on your FusionAuth instance.

The access token can be presented to APIs to authorize the request and the refresh token can be used to get a new access token.

There are 2 ways to interact with this SDK:

  1. By hosting your own server that performs the OAuth token exchange and meets the server code requirements for FusionAuth Web SDKs.
  2. By using the server hosted on your FusionAuth instance, i.e., not writing your own server code.

If you are hosting your own server, see server code requirements.

You can use this library against any version of FusionAuth or any OIDC compliant identity server.

Getting Started

Installation

NPM:

npm install @fusionauth/react-sdk

Yarn:

yarn add @fusionauth/react-sdk

Configuring Provider

To configure the SDK, wrap your app with FusionAuthProvider:

import React from 'react';
import { createRoot } from 'react-dom/client';
import { FusionAuthProvider } from '@fusionauth/react-sdk';
import App from './App';

const container = document.getElementById('root');
const root = createRoot(container!);

    root.render(
        <FusionAuthProvider
            clientID=""     // Your FusionAuth client ID
            serverUrl=""    // The URL of the server that performs the token exchange
            redirectUri=""  // The URI that the user is directed to after the login/register/logout action
        >
            <App />
        </FusionAuthProvider>
    );

Usage

Pre-built buttons

There are three pre-styled buttons that are configured to perform login/logout/registration. They can be placed anywhere in your app as is.

import {
  FusionAuthLoginButton,
  FusionAuthLogoutButton,
  FusionAuthRegisterButton
} from '@fusionauth/react-sdk';

export const LoginPage = () => (
  <>
    <h1>Welcome, please log in or register</h1>
    <FusionAuthLoginButton />
    <FusionAuthRegisterButton />
  </>
);

export const AccountPage = () => (
  <>
    <h1>Hello, user!</h1>
    <FusionAuthLogoutButton />
  </>
);

Programmatic usage

Alternatively, you may interact with the SDK programmatically using the useFusionAuth hook or withFusionAuth HOC.

useFusionAuth

Use the useFusionAuth hook with your functional components to get access to the properties exposed by FusionAuthContext:

import React from 'react';
import { useFusionAuth } from '@fusionauth/react-sdk';

const App = () => {
  const { login, logout, register, isAuthenticated } = useFusionAuth();

  return isAuthenticated ? (
    <div>
      <span>Hello, user!</span>
      <button onClick={() => logout()}>Logout</button>
    </div>
  ) : (
    <div>
      <button onClick={() => login()}>Log in</button>
      <button onClick={() => register()}>Register</button>
    </div>
  );
};

See useFusionAuth for more details.

withFusionAuth

The withFusionAuth higher-order component can be used to wrap your components and give them access to a fusionAuth prop which contains all the properties exposed by the FusionAuthContext. This works with both functional and class components:

Functional Component
import React from 'react';
import { withFusionAuth, WithFusionAuthProps } from '@fusionauth/react-sdk';

const LogoutButton: React.FC<WithFusionAuthProps> = props => {
  const { logout } = props.fusionAuth;

  return <button onClick={() => logout()}>Logout</button>;
}

export default withFusionAuth(LogoutButton);
Class Component
import React, { Component } from 'react';
import { withFusionAuth, WithFusionAuthProps } from '@fusionauth/react-sdk';

class LogoutButton extends Component<WithFusionAuthProps> {
  render() {
    const { logout } = this.props.fusionAuth;
    return <button onClick={() => logout()}>Logout</button>;
  }
}

export default withFusionAuth(LogoutButton);

See withFusionAuth for more details.

State parameter

The login and register functions both accept an optional string parameter called state. The state that is passed in to the function call will be passed back to the onRedirectSuccess handler on your FusionAuthProvider. Though you may pass any value you would like for the state parameter, it is often used to indicate which page the user was on before redirecting to login or registration, so that the user can be returned to that location after a successful authentication.

Protecting Content

The RequireAuth component can be used to protect information from unauthorized users. It takes an optional prop withRole that can be used to ensure the user has a specific role. If an array of roles is passed, the user must have at least one of the roles to be authorized.

import { RequireAuth, useFusionAuth } from '@fusionauth/react-sdk';

const UserNameDisplay = () => {
  const { user } = useFusionAuth();

  return (
    <RequireAuth>
      <p>User: {user.name}</p> // Only displays if user is authenticated
    </RequireAuth>
  );
};

const AdminPanel = () => (
  <RequireAuth withRole="admin">
    <button>Delete User</button> // Only displays if user is authenticated and has 'admin' role
  </RequireAuth>
);

Known Issues

Token exchange endpoint being called repeatedly

If you see the token exchange endpoint being called multiple times, this is due to a dev time setting in React 18. When running using StrictMode in development mode, React 18 will mount, unmount, and remount all components in this mode, which results in the network call running twice.

This will not happen in a production build or if StrictMode is disabled.

If you remove the React.StrictMode tags in index.tsx of the example app, the call is only made once.

Quickstart

See the FusionAuth React Quickstart for a full tutorial on using FusionAuth and React.

Documentation

Full library documentation

Usage With FusionAuth Cloud

When developing against a FusionAuth Cloud instance with a hostname ending in fusionauth.io, unless your application shares the same domain of fusionauth.io attempts to use these endpoints will fail with a 403 status code.

These endpoints do not work correctly for cross origin requests. Cross origin requests occur when the application making the request to FusionAuth is using a separate domain. For example, if your application URL is app.acme.com and the FusionAuth URL is acme.fusionauth.io requests from your application to FusionAuth will be considered cross origin.

If possible, have FusionAuth and your application served by the same domain, using a proxy if needed. For example, serve your app from app.acme.com and FusionAuth from auth.acme.com.

If this configuration is not possible, use one of these alternative methods:

Modifying FusionAuth CORS configuration options does not fix this issue because the cookies that FusionAuth writes will not be accessible cross domain.

Source Code

The source code is available here: https://github.com/FusionAuth/fusionauth-react-sdk/