Skip to main content

react

NextAuth.js methods and components that work in Client components and the Pages Router.

For use in Server Actions, check out these methods

SessionProvider()​

SessionProvider(props): Element

React Context provider to wrap the app (pages/) to make session data available anywhere.

When used, the session state is automatically synchronized across all open tabs/windows and they are all updated whenever they gain or lose focus or the state changes (e.g. a user signs in or out) when refetchOnWindowFocus is true.

info

You will likely not need SessionProvider if you are using the Next.js App Router (app/).

Parameters​

ParameterType
propsSessionProviderProps

Returns​

Element

signIn()​

signIn<P>( provider?, options?, authorizationParams?): Promise< P extends RedirectableProviderType ? SignInResponse | undefined : undefined >

Initiate a signin flow or send the user to the signin page listing all possible providers. Handles CSRF protection.

Type parameters​

ParameterDefault
P extends undefined | RedirectableProviderTypeundefined

Parameters​

ParameterType
provider?LiteralUnion< P extends RedirectableProviderType ? BuiltInProviderType | P : BuiltInProviderType, string >
options?SignInOptions
authorizationParams?SignInAuthorizationParams

Returns​

Promise< P extends RedirectableProviderType ? SignInResponse | undefined : undefined >

signOut()​

signOut<R>(options?): Promise< R extends true ? undefined : SignOutResponse >

Initiate a signout, by destroying the current session. Handles CSRF protection.

Type parameters​

ParameterDefault
R extends booleantrue

Parameters​

ParameterType
options?SignOutParams< R >

Returns​

Promise< R extends true ? undefined : SignOutResponse >

useSession()​

useSession<R>(options?): SessionContextValue< R >

React Hook that gives you access to the logged in user's session data and lets you modify it.

info

You will likely not need useSession if you are using the Next.js App Router (app/).

Type parameters​

Parameter
R extends boolean

Parameters​

ParameterType
options?UseSessionOptions< R >

Returns​

SessionContextValue< R >

SessionContextValue​

SessionContextValue: <R> R extends true ? {data: Session; status: "authenticated"; update: UpdateSession;} | {data: null; status: "loading"; update: UpdateSession;} : {data: Session; status: "authenticated"; update: UpdateSession;} | {data: null; status: "unauthenticated" | "loading"; update: UpdateSession;}

useSession() returns an object containing three things: a method called update, data and status.

Type parameters​

ParameterDefault
R extends booleanfalse

UpdateSession​

UpdateSession: (data?) => Promise< Session | null >

Todo​

Document

Parameters​

ParameterType
data?any

Returns​

Promise< Session | null >

SessionProviderProps​

If you have session expiry times of 30 days (the default) or more, then you probably don't need to change any of the default options.

However, if you need to customize the session behavior and/or are using short session expiry times, you can pass options to the provider to customize the behavior of the useSession hook.

Properties​

refetchInterval​

optional refetchInterval: number

A time interval (in seconds) after which the session will be re-fetched. If set to 0 (default), the session is not polled.

refetchOnWindowFocus​

optional refetchOnWindowFocus: boolean

SessionProvider automatically refetches the session when the user switches between windows. This option activates this behaviour if set to true (default).

refetchWhenOffline​

optional refetchWhenOffline: false

Set to false to stop polling when the device has no internet access offline (determined by navigator.onLine)

navigator.onLine documentation