useNextAuth

Important: This hook requires NextAuth.js to be properly configured in your application. Make sure your app is wrapped with NextAuth's <SessionProvider> component. See the NextAuth.js setup guide for complete installation instructions.

NextAuth.js Setup Required

This demo requires NextAuth.js to be properly configured

Missing SessionProvider: The useNextAuth hook requires your app to be wrapped in NextAuth's SessionProvider.

Setup Steps:

Install NextAuth.js: npm install next-auth
Configure NextAuth.js with your authentication providers
Wrap your app with <SessionProvider>
The hook will work once NextAuth.js is properly configured

See the NextAuth.js documentation for complete setup instructions.

Installation

Props

Prop	Type	Default	Description
`onSessionChange`	`(session: T \| null, status: string) => void`	`undefined`	Optional callback triggered when session changes
`refreshInterval`	`number`	`undefined`	Interval in milliseconds to refresh the session automatically
`onError`	`(error: Error) => void`	`undefined`	Optional callback for handling authentication errors

See NextAuth.js useSession for more details about the underlying session API.

Data

Property	Type	Description
`session`	`T \| null`	The current session object or null if not authenticated
`status`	`'authenticated' \| 'unauthenticated' \| 'loading'`	The current authentication status
`isAuthenticated`	`boolean`	Computed boolean indicating if user is authenticated
`signIn`	`typeof signIn`	NextAuth signIn function with error handling
`signOut`	`typeof signOut`	NextAuth signOut function with error handling
`refresh`	`() => Promise<void>`	Function to manually refresh the session

Key Features & Details

Built on NextAuth.js – see NextAuth.js Docs for full API.
Enhanced error handling with try-catch blocks and optional error callbacks.
Automatic session refresh at configurable intervals to keep sessions valid.
Session change detection with callbacks for analytics, logging, or UI updates.
Computed isAuthenticated property for easier conditional rendering.
Development mode logging of session and status changes.
Type-safe with TypeScript generics for custom session interfaces.

Common Use Cases

Protected routes with authentication checks and loading states.
Role-based access control with typed session data.
Automatic session refresh for long-running applications.
Error handling and user feedback for authentication failures.
Session change tracking for analytics and user experience.

Examples

NextAuth.js Setup

Before using the hook, ensure NextAuth.js is properly configured:

// app/layout.tsx or pages/_app.tsx
 
import { SessionProvider } from 'next-auth/react';
 
export default function App({
  Component,
  pageProps: { session, ...pageProps },
}) {
  return (
    <SessionProvider session={session}>
      <Component {...pageProps} />
    </SessionProvider>
  );
}

Basic Usage

const { session, status, isAuthenticated, signIn, signOut } = useNextAuth();
 
if (status === 'loading') {
  return <div>Loading...</div>;
}
 
if (isAuthenticated) {
  return (
    <div>
      <p>Welcome, {session?.user?.name}!</p>
      <button onClick={() => signOut()}>Sign Out</button>
    </div>
  );
}
 
return <button onClick={() => signIn()}>Sign In</button>;

With Session Change Callbacks

const { session, refresh } = useNextAuth({
  onSessionChange: (session, status) => {
    console.log('Session changed:', session, status);
    // Track session changes in analytics
  },
  onError: (error) => {
    console.error('Auth error:', error);
    // Handle authentication errors
  },
});
 
return (
  <div>
    <p>Current status: {status}</p>
    <button onClick={refresh}>Refresh Session</button>
  </div>
);

With Auto-Refresh

const { session, status } = useNextAuth({
  refreshInterval: 5 * 60 * 1000, // Refresh every 5 minutes
  onSessionChange: (session, status) => {
    if (status === 'unauthenticated') {
      // Redirect to login or show auth modal
      window.location.href = '/login';
    }
  },
});
 
return <div>Auto-refreshing session every 5 minutes</div>;

With Custom Session Type

import type { Session } from 'next-auth';
 
interface CustomSession extends Session {
  user: {
    id: string;
    name: string;
    email: string;
    role: 'admin' | 'user';
  };
}
 
const { session } = useNextAuth<CustomSession>();
 
// Now session.user.role is typed as 'admin' | 'user'
const isAdmin = session?.user?.role === 'admin';
 
return (
  <div>
    {isAdmin && <AdminPanel />}
    <UserDashboard />
  </div>
);

Protected Route Example

function ProtectedPage() {
  const { isAuthenticated, status } = useNextAuth();
 
  if (status === 'loading') return <Loading />;
  if (!isAuthenticated) return <Redirect to="/login" />;
 
  return <ProtectedContent />;
}

Error Handling with Toast

const { signIn, signOut } = useNextAuth({
  onError: (error) => {
    toast.error(`Authentication error: ${error.message}`);
  },
});
 
const handleSignIn = async () => {
  try {
    await signIn();
    toast.success('Signed in successfully!');
  } catch (error) {
    // Error already handled by onError callback
  }
};
 
return <button onClick={handleSignIn}>Sign In</button>;