Custom Layouts and Pages

Custom pages allow you to take full control over the layout and logic flow of authentication pages in your application. Instead of using the default pages provided by Stack Auth, you can build your own using our built-in components or low-level functions.

By default, StackHandler creates all authentication pages you need, however, you can replace them with your own custom implementations for a more tailored user experience.

Simple Example

For example, if you want to create a custom sign-in page with a customized title on the top, you can create a file at app/signin/page.tsx:

1
import { SignIn } from "@stackframe/stack";
2
3
export default function CustomSignInPage() {
4
  return (
5
    <div>
6
      <h1>My Custom Sign In page</h1>
7
      <SignIn />
8
    </div>
9
  );
10
}

Then you can instruct the Stack app in stack.ts to use your custom sign in page:

1
export const stackServerApp = new StackServerApp({
2
  // ...
3
  // add these three lines
4
  urls: {
5
    signIn: '/signin',
6
  }
7
});

You are now all set! If you visit the /signin page, you should see your custom sign in page. When users attempt to access a protected page or navigate to the default /handler/sign-in URL, they will automatically be redirected to your new custom sign-in page.

For more examples, please refer to the Examples.

Building From Scratch

While the simple approach above lets you customize the layout while using Stack’s pre-built components, sometimes you need complete control over both the UI and authentication logic.

We also provide the low-level functions powering our components, so that you can build your own logic. For example, to build a custom OAuth sign-in button, create a file at app/signin/page.tsx:

1
'use client';
2
import { useStackApp } from "@stackframe/stack";
3
4
export default function CustomOAuthSignIn() {
5
  const app = useStackApp();
6
7
  return (
8
    <div>
9
      <h1>My Custom Sign In page</h1>
10
      <button onClick={async () => {
11
        // This will redirect to the OAuth provider's login page.
12
        await app.signInWithOAuth('google');
13
      }}>
14
        Sign In with Google
15
      </button>
16
    </div>
17
  );
18
}

Again, edit the Stack app in stack.ts to use your custom sign in page:

1
export const stackServerApp = new StackServerApp({
2
  // ...
3
  // add these three lines
4
  urls: {
5
    signIn: '/signin',
6
  }
7
});

As above, visit the /signin page to see your newly created custom OAuth page.