React Mode Integration

@rootauth/react provides complete hosted authentication pages for React 18+. It includes the RootAuth Core API, page UI, and styles.

Preparation

Create an application in the RootAuth Console and copy the app_id (format: app_******).

Please add the following configuration line to the .npmrc file in the project root directory:

@rootauth:registry=http://gitlab.standard-software.co/api/v4/projects/12421/packages/npm/

1. Installation

@rootauth/react packages the complete RootAuth authentication UI as a React SDK and requires React 18.

npm install @rootauth/react react react-dom

2. Initialization

RootAuthClient accepts API, application, OIDC, Hosted-path, and success-callback options. The client can be passed to a React component or mounted through the imperative API.

import { RootAuthClient } from '@rootauth/react'

export const rootAuth = new RootAuthClient({
  app_id: 'your-app-id',
  api_base_url: 'https://rootauth-api.rootauth.com',
  redirect_uri: window.location.origin,
  scope: ['openid'],
  base_path: '/auth',
})

3. Configuration

The configuration object controls the application ID, API URL, redirect URI, authentication path, locale, and login or registration success behavior.

4. Use RootAuthMount

RootAuthMount creates the Hosted application within the React lifecycle and cleans it up automatically when the component unmounts. It receives an initialized RootAuth client.

import { RootAuthMount } from '@rootauth/react'
import { rootAuth } from './rootauth'

export function AuthPage() {
  return (
    <RootAuthMount
      client={rootAuth}
      containerId="rootauth-sdk"
      className="auth-page"
      style={{ minHeight: '100vh' }}
    />
  )
}

RootAuthMount props:

The component creates and cleans up the Hosted page within the React lifecycle.

5. Routing

React Router can render RootAuthMount under a wildcard route while RootAuth manages its internal login, registration, and password-reset pages according to base_path.

The host application owns React routing and renders RootAuthMount on the matching route. To obtain the shared Hosted path list:

import { getAuthRoutePaths } from '@rootauth/react'

const paths = getAuthRoutePaths('/auth')

getAuthRoutePaths('/auth') returns /auth, /auth/login, /auth/register, and /auth/reset-password. Host routers normally render RootAuthMount under /auth/*.

Login and registration methods are controlled by RootAuth application settings rather than a client type option. Pages display enabled email/password, email/code, phone/password, phone/code, or username/password methods.

6. Callback Example

onLoginSuccess and onRegisterSuccess receive successful results and can override default navigation. Returning false stops subsequent SDK navigation.

const rootAuth = new RootAuthClient({
  app_id: 'your-app-id',
  onLoginSuccess(data) {
    console.log('Login succeeded', data)
    return false
  },
  onRegisterSuccess(data) {
    console.log('Registration succeeded', data)
  },
})

7. Core API

The React client inherits Core API capabilities and can call login(), sendCode(), register(), resetPassword(), verifyLoginMfa(), logout(), and third-party login methods directly. The package also re-exports @rootauth/core types and helpers.

9. Related Modes

• @rootauth/core: API without UI
• @rootauth/web-components: Framework-independent form components
• @rootauth/vue: Complete Vue 3 Hosted pages