An SDK for using FusionAuth in React applications.
Table of Contents
Overview
This SDK manages authentication state for your React app and provides functionality to login, register, and logout users. It can be easily configured to automatically manage your refresh token and fetch user info.
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 newapp.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:
- By hosting your own server that performs the OAuth token exchange and meets the server code requirements for FusionAuth Web SDKs.
- 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
If you are new to React development, you may want to start with the Quickstart guide. If you are already familiar with React development, skip to the Installation section.
Quickstart
See the FusionAuth React Quickstart for a full tutorial on using FusionAuth and React.
Installation
NPM:
npm install @fusionauth/react-sdk
Yarn:
yarn add @fusionauth/react-sdk
Configuration
Wrap your app with FusionAuthProvider.
import ReactDOM from 'react-dom/client';
import { FusionAuthProviderConfig, FusionAuthProvider } from '@fusionauth/react-sdk';
const config: FusionAuthProviderConfig = {
clientId: "", // Your app's FusionAuth client id
redirectUri: "", // The URI that the user is directed to after the login/register/logout action
serverUrl: "", // The url of the server that performs the token exchange
shouldAutoFetchUserInfo: true, // Automatically fetch userInfo when logged in. Defaults to false.
shouldAutoRefresh: true, // Enables automatic token refresh. Defaults to false.
onRedirect: (state?: string) => { }, // Optional callback invoked upon redirect back from login or register.
// useDpop: true, // Opt-in to DPoP mode. See "DPoP Mode" below. Defaults to false.
};
ReactDOM.createRoot(document.getElementById("my-app")).render(
<FusionAuthProvider {...config}>
<App />
</FusionAuthProvider>
)
Configuration with NextJS
To configure the SDK with Next, install next-client-cookies and pass useCookies into the config object as nextCookieAdapter.
'use client'
import { useCookies } from 'next-client-cookies';
export default function Providers({ children }) {
return (
<FusionAuthProvider {...config} nextCookieAdapter={useCookies}>
{children}
</FusionAuthProvider>
);
}
Remember to wrap your layout in the <CookiesProvider/> from next-client-cookies/server.
Vercel has published a guide for rendering third party context providers in server components.
Usage
useFusionAuth
Once your app is wrapped in FusionAuthProvider, you can use useFusionAuth.
import { useFusionAuth } from '@fusionauth/react-sdk';
function MyComponent() {
const {
isLoggedIn,
isFetchingUserInfo,
startLogin,
startRegister,
userInfo
} = useFusionAuth()
if (isFetchingUserInfo) {
return <p>Loading...</p>
}
if (!isLoggedIn) {
return (
<div>
<button onClick={startLogin}>Login</button>
<p>or</p>
<button onClick={startRegister}>Register</button>
</div>
);
}
if (userInfo?.given_name) {
return <p>Welcome {userInfo.given_name}!</p>
}
}
Alternatively, you may interact with the SDK using the withFusionAuth higher-order component.
State Parameter
The startLogin and startRegister functions accept an optional string parameter: state. The value passed in will be passed to the onRedirect callback on your FusionAuthProviderConfig. 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. The Unauthenticated component provides the inverse functionality.
import { RequireAuth, useFusionAuth } from '@fusionauth/react-sdk';
const UserNameDisplay = () => {
const { userInfo } = useFusionAuth();
return (
<>
<RequireAuth>
<p>User: {userInfo.given_name}</p> // Only displays if user is authenticated
</RequireAuth>
<Unauthenticated>
<p>Please log in to view this page</p>
</Unauthenticated>
</>
);
};
const AdminPanel = () => (
<RequireAuth withRole="admin">
<button>Delete User</button> // Only displays if user is authenticated and has 'admin' role
</RequireAuth>
);
UI Components
This SDK offers 3 pre-built UI components.
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 />
</>
);
DPoP Mode
By default, the SDK calls a Hosted Backend that stores tokens in HttpOnly cookies (useDpop: false, the default). In DPoP mode, the SDK instead calls FusionAuth endpoints directly and binds tokens to a private key generated in the browser, per RFC 9449. Enable it by setting useDpop: true on FusionAuthProviderConfig:
const config: FusionAuthProviderConfig = {
clientId: "",
redirectUri: "",
serverUrl: "",
useDpop: true, // Opt-in to DPoP mode.
dpopTokenStorage: 'localStorage', // 'localStorage' (default, persists across reloads) or 'memory'.
};
When useDpop: true, useFusionAuth() additionally returns dpopFetch, generateProof, and getAccessToken. These are undefined when useDpop is false or not set.
const { dpopFetch, generateProof, getAccessToken } = useFusionAuth();
// Recommended — handles attaching DPoP headers (and nonce retries) automatically.
const response = await dpopFetch('https://api.example.com/data', { method: 'GET' });
// Advanced — for axios or other HTTP libraries that can't use dpopFetch.
const accessToken = getAccessToken();
const proof = await generateProof('https://api.example.com/data', 'GET', accessToken);
// axios.get('https://api.example.com/data', {
// headers: { Authorization: `DPoP ${accessToken}`, DPoP: proof }
// });
Known Issues
None.
Documentation
These docs are generated with typedoc and configured with typedoc-plugin-markdown.
Formatting
There are several linting packages run when you push to a branch. One is prettier. If this fails, you can fix the files from the command line:
- npm run install
- npm run prettier -- -w /path/to/file
Doing this will overwrite your file, but fix prettier's objections.
Releases
This package is released via GitHub actions.
Upgrade Policy
This library may periodically receive updates with bug fixes, security patches, tests, code samples, or documentation changes.
These releases may also update dependencies, language engines, and operating systems, as we'll follow the deprecation and sunsetting policies of the underlying technologies that the libraries use.
This means that after a dependency (e.g. language, framework, or operating system) is deprecated by its maintainer, this library will also be deprecated by us, and may eventually be updated to use a newer version.