Conditional authentication UI
A client component needs to render different UI for loading, authenticated, and unauthenticated users.
Auth.js · Hook
useSession
useSession is a client-side React hook for reading and updating the current Auth.js session. It returns session data, authentication status, and an update method.
How it works
useSession is a client-side React hook that reads the current Auth.js session and provides its data, loading or authentication status, and an update method. In a Next.js App Router application, use the server-side auth() export instead when the component does not need client-side session behavior.
Syntax
function useSession<R>(options?): SessionContextValue<R>Parameters
| Name | Type | Description |
|---|---|---|
options | UseSessionOptions<R> | Optional configuration controlling hook behavior. |
Returns
SessionContextValue<R>, containing update, data, and status.
Key points
- Use the hook to read the current logged-in user's session and request session updates from a client component.
- Its result has three main fields: update, data, and status.
- The generic signature accepts optional options and returns SessionContextValue<R>.
- The integration supports useSession in Next.js Client Components and the Pages Router.
Common mistakes
- Do not use this hook for server-side session access; prefer auth() in the App Router.
- SessionProvider options may be needed when session expiry is short or session behavior requires customization.
Example: Read the client session
"use client"
import { SessionProvider, useSession } from "next-auth/react"
function Profile() {
const { data: session, status } = useSession()
if (status === "loading") return <p>Loading...</p>
if (!session) return <p>Not signed in</p>
return <p>Signed in as {session.user?.email}</p>
}
export default function Page() {
return (
<SessionProvider>
<Profile />
</SessionProvider>
)
}Wrap the component tree in SessionProvider, then use the hook to inspect loading, authenticated, and unauthenticated states.
When to use it
Pages Router session access
A Pages Router application needs access to the current user session in a React component.
Client session updates
A client-side flow needs to refresh or modify session state after an authenticated action.
Interview questions
QWhat does useSession return?
useSession() returns a SessionContextValue containing data, status, and update. The data value is the session when authenticated and can be null when no session exists.
Follow-up: How should session access differ in the App Router? Prefer the auth() export for server-side access rather than using this client-only hook.
QWhere can useSession be used?
The hook is intended for client-side use. In Next.js, it works with Client Components and the Pages Router, while a SessionProvider supplies the React context used by the hook.
Follow-up: What must be added around a component that calls the hook? Place it inside an Auth.js SessionProvider.
QHow can the hook's behavior or session be customized?
The hook accepts an optional UseSessionOptions<R> argument and exposes an update method. That update method lets the application modify the session through the client session API.
Follow-up: What additional configuration can affect its behavior? Provider options can customize behavior, particularly for short session-expiry periods.
Related
SessionProviderSessionContextValueUseSessionOptionsauthsignInsignOut