react

NextAuth.js is the official integration of Auth.js for Next.js applications. It supports both Client Components and the Pages Router. It includes methods for signing in, signing out, hooks, and a React Context provider to wrap your application and make session data available anywhere.

For use in Server Actions, check out these methods

GetSessionParams

Properties

broadcast?

optional broadcast: boolean;

event?

optional event: string;

triggerEvent?

optional triggerEvent: boolean;

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

basePath?

optional basePath: string;

baseUrl?

optional baseUrl: string;

children

children: ReactNode;

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

session?

optional session: null | Session;

SignInOptions<Redirect>

Extends

• Record<string, unknown>

Type parameters

Properties

callbackUrl?

optional callbackUrl: string;

Deprecated

Use redirectTo instead.

redirect?

optional redirect: Redirect;

You might want to deal with the signin response on the same page, instead of redirecting to another page. For example, if an error occurs (like wrong credentials given by the user), you might want to show an inline error message on the input field.

For this purpose, you can set this to option redirect: false.

redirectTo?

optional redirectTo: string;

Specify where the user should be redirected to after a successful signin.

By default, it is the page the sign-in was initiated from.

SignInResponse

Properties

code

code: undefined | string;

error

error: undefined | string;

ok

ok: boolean;

status

status: number;

url

url: null | string;

SignOutParams<Redirect>

Type parameters

Properties

callbackUrl?

optional callbackUrl: string;

Deprecated

Use redirectTo instead.

redirect?

optional redirect: Redirect;

[Documentation](https://next-auth.js.org/getting-started/client#using-the-redirect-false-option-1

redirectTo?

optional redirectTo: string;

If you pass redirect: false, the page will not reload. The session will be deleted, and useSession is notified, so any indication about the user will be shown as logged out automatically. It can give a very nice experience for the user.

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

UpdateSession()

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

Todo

Document

Parameters

Returns

Promise<Session | null>

SessionContext

const SessionContext: Context<undefined | {
  data: Session;
  status: "authenticated";
  update: UpdateSession;
  } | {
  data: null;
  status: "loading" | "unauthenticated";
  update: UpdateSession;
}>;

__NEXTAUTH

const __NEXTAUTH: AuthClientConfig;

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.

Parameters

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 | Record<ProviderId, ClientSafeProvider>>

Returns

Promise<null | Record<ProviderId, ClientSafeProvider>>

getSession()

getSession(params?): Promise<null | Session>

Parameters

Returns

Promise<null | Session>

signIn()

signIn(provider, options, authorizationParams)

signIn(
   provider?, 
   options?, 
authorizationParams?): Promise<void>

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

Parameters

Returns

Promise<void>

Note

This method can only be used from Client Components (“use client” or Pages Router). For Server Actions, use the signIn method imported from the auth config.

signIn(provider, options, authorizationParams)

signIn(
   provider?, 
   options?, 
authorizationParams?): Promise<SignInResponse>

Parameters

Returns

Promise<SignInResponse>

signOut()

signOut(options)

signOut(options?): Promise<void>

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

Parameters

Returns

Promise<void>

Note

This method can only be used from Client Components (“use client” or Pages Router). For Server Actions, use the signOut method imported from the auth config.

signOut(options)

signOut(options?): Promise<SignOutResponse>

Parameters

Returns

Promise<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.

Type parameters

Parameters

Returns

SessionContextValue<R>