useAuth

Overview

The useAuth hook provides access to authentication state and handles automatic redirects based on authentication status and middleware configuration.

Signature

function useAuth(options?: AuthOptions): AuthContextType

Parameters

AuthOptions

Configuration options for authentication behavior

Show AuthOptions properties

'auth' | 'guest' | undefined

Defines the authentication requirement for the current page:

'auth': Requires authentication (redirects unauthenticated users)
'guest': Guest-only page (redirects authenticated users)
undefined: No automatic redirects

string

default:"/404"

URL to redirect to when middleware: 'auth' and user is not authenticated

string

URL to redirect to when middleware: 'guest' and user is authenticated

Navigation behavior options

Show NavigationOptions properties

boolean

default:false

Use replaceState instead of pushState for navigation

boolean

default:false

Force navigation even if already on the same page

Returns

object

Authentication context object containing user state and authentication methods

Show AuthContextType properties

LogtoUser | null

Current authenticated user object, or null if not authenticated

Show LogtoUser properties

string

required

Unique user identifier

string

User’s display name

string

User’s email address

string

URL to user’s avatar image

boolean

Loading state indicator for user authentication status

Function to initiate sign-in flow

(options?: { callbackUrl?: string; global?: boolean }) => Promise<void>

Function to sign out the current user

() => Promise<void>

Function to refresh authentication state

Whether popup sign-in is enabled

Examples

Basic Usage

import { useAuth } from '@ouim/logto-authkit'

function Profile() {
  const { user, isLoadingUser } = useAuth()

  if (isLoadingUser) {
    return <div>Loading...</div>
  }

  if (!user) {
    return <div>Not authenticated</div>
  }

  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      <p>Email: {user.email}</p>
    </div>
  )
}

Protected Route

import { useAuth } from '@ouim/logto-authkit'

function Dashboard() {
  const { user, signOut } = useAuth({
    middleware: 'auth',
    redirectTo: '/login'
  })

  return (
    <div>
      <h1>Dashboard</h1>
      <p>Welcome, {user?.name}</p>
      <button onClick={() => signOut()}>Sign Out</button>
    </div>
  )
}

Guest-Only Route

import { useAuth } from '@ouim/logto-authkit'

function Login() {
  const { signIn } = useAuth({
    middleware: 'guest',
    redirectIfAuthenticated: '/dashboard'
  })

  return (
    <div>
      <h1>Login</h1>
      <button onClick={() => signIn()}>Sign In</button>
    </div>
  )
}

import { useAuth } from '@ouim/logto-authkit'

function ProtectedPage() {
  const { user } = useAuth({
    middleware: 'auth',
    redirectTo: '/login',
    navigationOptions: {
      replace: true, // Use replace instead of push
      force: false
    }
  })

  return <div>Protected content</div>
}

Behavior

The hook automatically handles redirects based on the middleware option and authentication state
Redirects only occur after the loading state completes (isLoadingUser is false)
When middleware: 'auth' is set and user is not authenticated, redirects to redirectTo (defaults to /404)
When middleware: 'guest' is set and user is authenticated, redirects to redirectIfAuthenticated
The hook memoizes options to prevent infinite re-renders when the options object reference changes

Get Started

Frontend

Server

Configuration

Examples

API Reference

Overview

Signature

Parameters

Returns

Examples

Basic Usage

Protected Route

Guest-Only Route

Custom Navigation Options

Behavior

See Also