Skip to main content
AuthGuard is a client-side UX gate, not a security boundary. It prevents rendering protected UI for unauthenticated users — it does not prevent API calls. Every API endpoint must authenticate requests independently.

​
Basic usage

Place AuthGuard around any route or section that requires authentication. The fallback prop is rendered when the user is not authenticated; loadingFallback is rendered while auth state is being restored. 
// app/(protected)/layout.tsx
'use client'

import { AuthGuard } from 'ailita-library'
import { useRouter } from 'next/navigation'
import { useEffect } from 'react'

export default function ProtectedLayout({ children }: { children: React.ReactNode }) {
  return (
    <AuthGuard
      fallback={<RedirectToLogin />}
      loadingFallback={<div>Loading...</div>}
    >
      {children}
    </AuthGuard>
  )
}

function RedirectToLogin() {
  const router = useRouter()
  useEffect(() => { router.push('/login') }, [router])
  return null
}
Always provide loadingFallback. During the ~200-500ms silent token refresh on mount, isAuthenticated is false and isLoading is true. Without loadingFallback, every authenticated user sees a flash redirect to /login on every page load.

​
Props

​
fallback
ReactNode
required
Rendered when the user is not authenticated or lacks required roles. Typically a redirect component (<Navigate to="/login" /> in React Router) or a useEffect-based redirect (Next.js App Router).
​
loadingFallback
ReactNode
default:"null"
Rendered while authentication state is being restored (silent token refresh on mount). Always provide this — the ~200-500ms refresh window causes a redirect flash without it.
​
requiredRoles
string[]
Optional list of role names the user must have. Uses AND logic — all listed roles must be present. Role strings come from the backend. There is no client-side enum.

​
Role-protected routes

requiredRoles uses AND logic — all listed roles must be present. A user with ['ADMIN'] will NOT pass requiredRoles={['ADMIN', 'SUPER_ADMIN']}.
<AuthGuard
  fallback={<Navigate to="/forbidden" replace />}
  loadingFallback={<Spinner />}
  requiredRoles={['ADMIN']}
>
  <AdminPanel />
</AuthGuard>

​
How AuthGuard evaluates state

AuthGuard checks three conditions in order, matching the source code logic:
  1. If isLoading is true — renders loadingFallback
  2. If isAuthenticated is false — renders fallback
  3. If requiredRoles is set and user does not have ALL listed roles — renders fallback
  4. Otherwise — renders children

​
What AuthGuard does not do

  • Does not make any network requests
  • Does not verify tokens (that is AuthProvider’s responsibility via silent refresh)
  • Does not integrate with the server — it is purely client-side React rendering logic

​
Next steps

Quickstart

See a complete end-to-end integration example with AilitaProvider, AuthGuard, and LoginForm.