FusionAuth React SDK

An SDK for using FusionAuth in React applications.

Table of Contents

- Overview
- Getting Started
- Installation
- Configuring Provider
- Server Code Requirements
- Usage
- Pre-built buttons
- Programmatic usage
- Protecting content
- Documentation

Overview

This SDK supports authentication via the Authorization Code Grant. Once authentication succeeds, the following secure,
HTTP-only cookies will be set:

- access_token - an OpenID Id Token
- refresh_token - a Refresh Token used to obtain a new access_token. This cookie will only be set if refresh tokens are enabled on your FusionAuth instance.

Note that this setup requires you to have a server
that performs the OAuth token exchange. See Server Code Requirements for more details.

Getting Started

$3

NPM:
``bash
npm install fusionauth-react-sdk
``

Yarn:
`bash
yarn add fusionauth-react-sdk
``

$3


To configure the SDK, wrap your app with FusionAuthProvider:

`tsx
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(
baseUrl="" // The base URL of your FusionAuth instance
clientID="" // Your FusionAuth client ID
serverUrl="" // The base URL of your server for the token exchange
redirectUri="" // The URI that the user is directed to after the login/register/logout action
>


);
`

$3

Authenticating with FusionAuth requires you to set up a server that will be used to perform
the OAuth token exchange. This server must have the following endpoints:

#### POST /token-exchange
This endpoint must:

1. Call /oauth2/token
to complete the Authorization Code Grant request. The code and code_verifier parameters should come from the
request body, while the rest of the parameters should be set/configured on the server side.
2. Once the token exchange succeeds, read the access_token from the response body and set it as a secure, HTTP-only cookie with the same name.
3. If you wish to support refresh tokens, repeat step 2 for the refresh_token cookie.
4. Call /oauth2/userinfo to retrieve the user info object
and respond back to the client with this object.

Example implementation

#### POST /jwt-refresh (optional)

This endpoint is necessary if you wish to use refresh tokens. This endpoint must:

1. Call /api/jwt/refresh to get a new access_token and
refresh_token.
2. Update the access_token and refresh_token cookies from the response.

Example implementation

Usage

$3

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

`tsx
import {
FusionAuthLoginButton,
FusionAuthLogoutButton,
FusionAuthRegisterButton
} from 'fusionauth-react-sdk';

export const LoginPage = () => (
<>


Welcome, please log in or register



);

export const AccountPage = () => (
<>


Hello, user!



);
`

$3

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:

`tsx
import React from 'react';
import { useFusionAuth } from 'fusionauth-react-sdk';

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

return isAuthenticated ? (


) : (

login()}>Log in
register()}>Register

);
};
`

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

`tsx
import React from 'react';
import { withFusionAuth, WithFusionAuthProps } from 'fusionauth-react-sdk';

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

return logout()}>Logout;
}

export default withFusionAuth(LogoutButton);
`

##### Class Component

`tsx
import React, { Component } from 'react';
import { withFusionAuth, WithFusionAuthProps } from 'fusionauth-react-sdk';

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

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.

$3

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.

`tsx
import { RequireAuth, useFusionAuth } from 'fusionauth-react-sdk';

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

return (



User: {user.name}

// Only displays if user is authenticated

);
};

const AdminPanel = () => (

Delete User // Only displays if user is authenticated and has 'admin' role

);
``

Example App

See the FusionAuth React SDK Example for functional example of a React client that utilizes the SDK as well as an Express server that performs the token exchange.

Documentation

Full library documentation