CustomizationCustom Page Examples

Forgot Password

This page provides examples of how to create custom “forgot password” pages for your application. The forgot password functionality allows users to request a password reset email when they can’t remember their current password.

Custom page with ForgotPassword component

The ForgotPassword component provides a complete form for users to request a password reset email. When a user submits their email, Stack Auth will send them an email with a link to reset their password.

1'use client';
2import { ForgotPassword } from "@stackframe/stack";
3
4export default function DefaultForgotPassword() {
5  return <ForgotPassword />;
6}

Integration with Application Routing

To integrate the forgot password page with your application’s routing:

  1. Create a route for your forgot password page (e.g., /forgot-password)
  2. Configure Stack Auth to use your custom route in your stack.ts file:
1export const stackServerApp = new StackServerApp({
2  // ...
3  urls: {
4    forgotPassword: '/forgot-password',
5  }
6});

This ensures that links to the forgot password page will direct users to your custom implementation. When a user submits their email, Stack Auth will send them an email with a link to the password reset page configured in your application.

Custom forgot password form

If you need more control over the forgot password process, you can build your own form. This approach allows you to customize the UI and error handling to match your application’s design.

1'use client';
2
3import { useStackApp } from "@stackframe/stack";
4import { useState } from "react";
5
6export default function CustomForgotPasswordForm() {
7  const [email, setEmail] = useState('');
8  const [error, setError] = useState('');
9  const [message, setMessage] = useState('');
10  const app = useStackApp();
11
12  const onSubmit = async () => {
13    if (!email) {
14      setError('Please enter your email address');
15      return;
16    }
17    
18    try {
19      const result = await app.sendForgotPasswordEmail(email);
20      if (result?.status === 'error') {
21        if (result.error.code === 'user_not_found') {
22          // For security reasons, don't reveal if a user exists or not
23          setMessage('If an account exists with this email, a password reset link has been sent.');
24        } else {
25          setError(`Error: ${result.error.message}`);
26        }
27      } else {
28        setMessage('Password reset email sent! Please check your inbox.');
29      }
30    } catch (err) {
31      setError(`An unexpected error occurred: ${err.message}`);
32    }
33  };
34  
35  return (
36    <form onSubmit={(e) => { e.preventDefault(); onSubmit(); }}>
37      {error && <div>{error}</div>}
38      {message ? (
39        <div>{message}</div>
40      ) : (
41        <>
42          <input
43            type='email'
44            placeholder="email@example.com"
45            value={email}
46            onChange={(e) => setEmail(e.target.value)}
47          />
48          <button type='submit'>Reset Password</button>
49        </>
50      )}
51    </form>
52  ); 
53}