Custom sign-in experience
An application needs branded authentication UI instead of the default Auth.js sign-in screen.
Auth.js · Pipe
pages
Auth.js custom pages map page types such as signIn to application routes. Configured routes replace the matching built-in pages and must exist in the application.
How it works
The pages configuration maps Auth.js page types to application routes. Setting signIn replaces the corresponding built-in sign-in page, so the configured route must exist in the application.
Syntax
pages: { signIn: "/login" }Parameters
| Name | Type | Description |
|---|---|---|
pages | Partial<PagesOptions> | A partial mapping from Auth.js page types to application URL paths, such as signIn, signOut, error, verifyRequest, and newUser. |
Key points
- Use page-type keys such as
signInand assign each one the application route that should handle it. - Custom page routing is enabled by adding a
pagesobject to the Auth.js configuration. - A sign-in page can be redirected to a custom
/loginroute throughpages.signIn. - A configured custom route takes precedence over Auth.js's built-in page for that page type.
Common mistakes
- The configured route must correspond to a real page in the application.
Example: Configure a custom sign-in route
import NextAuth from "next-auth"
import GitHub from "next-auth/providers/github"
export const { handlers, auth, signIn, signOut } = NextAuth({
providers: [GitHub],
pages: {
signIn: "/login",
},
})Configure Auth.js to use an application route at /login for sign-in.
When to use it
Customize authentication flow pages
An application needs dedicated routes for sign-out, errors, email verification, or first-time users.
Selective page overrides
An application wants to keep Auth.js defaults for most page types while replacing only selected pages.
Interview questions
QWhat is the purpose of the pages option?
The pages object customizes Auth.js routes by mapping a page type, such as signIn, to a path. Auth.js uses that path instead of the matching built-in page.
Follow-up: What happens if signIn is configured but the route is missing? The authentication flow points to a page that does not exist, so the application must create the route.
QHow do you configure a custom sign-in page?
Set pages.signIn to the route for the custom sign-in page, for example signIn: "/login". The route must be implemented by the application.
Follow-up: How can the custom page render the available providers? Export a provider map containing each provider's id and name, then use it when rendering sign-in controls.
QWhat is the relationship between custom and built-in pages?
Custom page settings override the corresponding built-in Auth.js pages. Built-in pages remain available for page types that are not customized.
Follow-up: Why might an application keep built-in pages? They provide authentication UI without requiring the application to implement every page from scratch.
Related
PagesOptionssignInsignOuterrorverifyRequestnewUserBuilt-in PagesCustom Sign-in Page