Expose session context
A Pages Router application needs useSession() in nested client components.
Auth.js · Component
SessionProvider
SessionProvider is a client-side React Context provider for the Next.js Pages Router. It makes session data available to descendants and coordinates session updates across browser tabs and windows.
How it works
SessionProvider is a client-only React Context provider for Next.js Pages Router applications. It makes session data available to descendants, synchronizes session state across open tabs and windows, and can refetch when windows regain focus or when a configured interval elapses.
Syntax
function SessionProvider(props): ElementParameters
| Name | Type | Description |
|---|---|---|
props | SessionProviderProps | Provider properties, including an optional session value and session-refetch configuration. |
Returns
Element
Key points
- Wrap the Pages Router application to expose session information throughout its component tree.
- Open browser contexts receive coordinated session-state updates.
- Focus transitions can cause the provider to refresh session information.
- Sign-in and sign-out state changes are propagated to connected provider instances.
- refetchInterval expresses polling frequency in seconds.
- refetchOnWindowFocus controls focus-triggered refetching and defaults to true.
Common mistakes
- Do not use SessionProvider as the server-side session mechanism; with the App Router, prefer the auth() export.
- A nonzero refetchInterval enables polling, while zero disables it.
- Window-focus refetching is enabled by default and can affect session traffic.
Example: Provide session context
import { SessionProvider } from "next-auth/react"
import Dashboard from "./Dashboard"
export default function App({ session }) {
return (
<SessionProvider session={session}>
<Dashboard />
</SessionProvider>
)
}Wrap the client-side application so Dashboard and its descendants can use useSession().
When to use it
Synchronize browser contexts
Several tabs must reflect sign-in or sign-out changes.
Control session revalidation
The application needs periodic or focus-based session refreshes.
Interview questions
QWhat does SessionProvider do?
It is a React Context provider that wraps a Pages Router application and exposes session data to descendant components. It is intended for client-side use, commonly together with useSession().
Follow-up: What should an App Router application prefer? Use the auth() export for server-side session access rather than relying on SessionProvider.
QHow is session state synchronized?
The provider synchronizes session state across open tabs and windows. With refetchOnWindowFocus enabled, focus changes and authentication-state changes trigger updates.
Follow-up: How can polling be controlled? Set refetchInterval to a number of seconds; zero, the default, disables polling.
QHow can initial session data and behavior be configured?
Pass the server-provided session through the session prop when initializing the provider, as shown for the Pages Router. Provider options can also customize useSession behavior.
Follow-up: When might customization be useful? Short session expiry times or a need to change refetch behavior are cases called out by the documentation.
Related
useSessionSessionProviderPropsauthNextAuth