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 SessionProviderProps.refetchOnWindowFocus is true.

info

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

Parameters​

▪ props: SessionProviderProps

Returns​

Element

getCsrfToken()​

getCsrfToken(): Promise< string >

Returns the current Cross-Site Request Forgery Token (CSRF Token) required to make requests that changes state. (e.g. signing in or out, or updating the session).

CSRF Prevention: Double Submit Cookie

Returns​

Promise< string >

getProviders()​

getProviders(): Promise< null | ProvidersType >

Returns a client-safe configuration object of the currently available providers.

Returns​

Promise< null | ProvidersType >

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​

▪ P extends undefined | RedirectableProviderType = undefined

Parameters​

▪ provider?: LiteralUnion< P extends RedirectableProviderType ? BuiltInProviderType | P : BuiltInProviderType >

▪ 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​

▪ R extends boolean = true

Parameters​

▪ 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​

▪ R extends boolean

Parameters​

▪ options?: UseSessionOptions< R >

Returns​

SessionContextValue< R >

SessionContextValue<R>​

type 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​

▪ R extends boolean = false

UpdateSession​

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

Parameters​

▪ data?: any

Returns​

Promise< Session | null >

Todo​

Document

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​

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​

refetchOnWindowFocus?: boolean;

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

refetchWhenOffline​

refetchWhenOffline?: false;

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

navigator.onLine documentation