Supabase reset password and forgot password in the Next.js App Router

A Supabase password reset that works with @supabase/ssr: a forgot password page that sends the email, a token_hash link checked on your server, a change password page behind a real session, and the errors people actually hit (auth session missing, a link that expired before anyone clicked it, the same password twice). It ends with the Spotlight Lamp Login as the sign-in page whose Forgot password link starts the flow.

One payment$3

By buying you agree to the Terms.

One payment, no subscription
Download right after paying
Use it in client projects
Won't run on the listed stack? We fix it or refund you

Ready forCursorv0Lovableshadcn CLI

Full product pageReact · Tailwind · TypeScript

The Supabase reset flow in the App Router

app/forgot-password/actions.ts

"use server";
import { createClient } from "@/lib/supabase/server";

const SITE = process.env.NEXT_PUBLIC_SITE_URL!; // e.g. https://app.example.com, no trailing slash

export type ResetState = { sent: boolean; message: string };

export async function requestPasswordReset(_prev: ResetState, formData: FormData): Promise<ResetState> {
  const email = String(formData.get("email") ?? "").trim();
  if (!email.includes("@")) return { sent: false, message: "Enter the email you signed up with." };

  const supabase = await createClient();
  const { error } = await supabase.auth.resetPasswordForEmail(email, {
    // Must be on your Redirect URLs list in Supabase. The email template below decides the real link.
    redirectTo: `${SITE}/account/update-password`,
  });

  if (error?.code === "over_email_send_rate_limit") {
    return { sent: false, message: "Too many reset emails for now. Wait a few minutes and try again." };
  }
  // Same answer whether or not the account exists. Supabase does the same, so nobody can probe for emails.
  return { sent: true, message: "If that email has an account, a reset link is on its way. Check your inbox and spam." };
}

app/forgot-password/page.tsx

"use client";
import { useActionState } from "react";
import { requestPasswordReset, type ResetState } from "./actions";

const initial: ResetState = { sent: false, message: "" };

export default function ForgotPasswordPage() {
  const [state, formAction, pending] = useActionState(requestPasswordReset, initial);

  return (
    <main className="mx-auto grid min-h-dvh max-w-sm content-center gap-4 p-6">
      <h1 className="text-2xl font-semibold">Reset your password</h1>
      {state.sent ? (
        <p role="status">{state.message}</p>
      ) : (
        <form action={formAction} className="grid gap-3">
          <label htmlFor="email" className="text-sm">Email</label>
          <input id="email" name="email" type="email" autoComplete="email" required className="rounded-md border px-3 py-2" />
          {state.message ? <p role="alert" className="text-sm text-red-500">{state.message}</p> : null}
          <button type="submit" disabled={pending} className="rounded-md bg-black px-3 py-2 text-white disabled:opacity-60">
            {pending ? "Sending..." : "Send reset link"}
          </button>
        </form>
      )}
      <a href="/login" className="text-sm underline">Back to sign in</a>
    </main>
  );
}

Supabase dashboard: Authentication > Emails > Reset Password

<h2>Reset your password</h2>
<p>We received a request to reset your password. Follow the link below to choose a new one.</p>
<p>
  <a href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=recovery&next=/account/update-password">Reset password</a>
</p>

app/auth/confirm/route.ts

import { type EmailOtpType } from "@supabase/supabase-js";
import { type NextRequest, NextResponse } from "next/server";
import { createClient } from "@/lib/supabase/server";

// The reset email links here: /auth/confirm?token_hash=...&type=recovery&next=/account/update-password
export async function GET(request: NextRequest) {
  const { searchParams } = request.nextUrl;
  const token_hash = searchParams.get("token_hash");
  const type = searchParams.get("type") as EmailOtpType | null;
  const nextParam = searchParams.get("next") ?? "/";
  // Only follow paths on this site, so the link can't be turned into an open redirect.
  const next = nextParam.startsWith("/") && !nextParam.startsWith("//") ? nextParam : "/";

  const redirectTo = request.nextUrl.clone();
  redirectTo.search = "";

  if (token_hash && type) {
    const supabase = await createClient();
    const { error } = await supabase.auth.verifyOtp({ type, token_hash });
    if (!error) {
      redirectTo.pathname = next; // the recovery session cookie is set now
      return NextResponse.redirect(redirectTo);
    }
  }

  redirectTo.pathname = "/auth/auth-code-error";
  return NextResponse.redirect(redirectTo);
}

app/account/update-password/page.tsx

import { redirect } from "next/navigation";
import { createClient } from "@/lib/supabase/server";
import UpdatePasswordForm from "./form";

export default async function UpdatePasswordPage() {
  const supabase = await createClient();
  const { data } = await supabase.auth.getClaims();
  // No session means the link was not opened, or it was opened in another browser.
  if (!data?.claims) redirect("/auth/auth-code-error");

  return (
    <main className="mx-auto grid min-h-dvh max-w-sm content-center gap-4 p-6">
      <h1 className="text-2xl font-semibold">Choose a new password</h1>
      <p className="text-sm opacity-70">For {data.claims.email}</p>
      <UpdatePasswordForm />
    </main>
  );
}

app/account/update-password/form.tsx

"use client";
import { useActionState } from "react";
import { updatePassword, type UpdateState } from "./actions";

export default function UpdatePasswordForm() {
  const [state, formAction, pending] = useActionState(updatePassword, { message: "" } satisfies UpdateState);

  return (
    <form action={formAction} className="grid gap-3">
      <label htmlFor="password" className="text-sm">New password</label>
      <input id="password" name="password" type="password" autoComplete="new-password" minLength={8} required className="rounded-md border px-3 py-2" />
      <label htmlFor="confirm" className="text-sm">Type it again</label>
      <input id="confirm" name="confirm" type="password" autoComplete="new-password" minLength={8} required className="rounded-md border px-3 py-2" />
      {state.message ? <p role="alert" className="text-sm text-red-500">{state.message}</p> : null}
      <button type="submit" disabled={pending} className="rounded-md bg-black px-3 py-2 text-white disabled:opacity-60">
        {pending ? "Saving..." : "Save new password"}
      </button>
    </form>
  );
}

app/account/update-password/actions.ts

"use server";
import { isAuthSessionMissingError } from "@supabase/supabase-js";
import { redirect } from "next/navigation";
import { createClient } from "@/lib/supabase/server";

export type UpdateState = { message: string };

export async function updatePassword(_prev: UpdateState, formData: FormData): Promise<UpdateState> {
  const password = String(formData.get("password") ?? "");
  if (password.length < 8) return { message: "Use at least 8 characters." };
  if (password !== formData.get("confirm")) return { message: "The two passwords don't match." };

  const supabase = await createClient();
  const { error } = await supabase.auth.updateUser({ password });

  if (error) {
    if (isAuthSessionMissingError(error)) return { message: "Your reset link has expired. Ask for a new one." };
    if (error.code === "same_password") return { message: "That's your current password. Pick a new one." };
    if (error.code === "weak_password") return { message: error.message }; // lists what your password rules need
    return { message: "Couldn't save the password. Try again." };
  }

  // The user is signed in with the new password now.
  redirect("/dashboard");
}

app/auth/auth-code-error/page.tsx

export default function AuthCodeError() {
  return (
    <main className="mx-auto grid min-h-dvh max-w-sm content-center gap-3 p-6">
      <h1 className="text-xl font-semibold">That link has expired or was already used</h1>
      <p>Reset links work once and only for a limited time. Ask for a new one and open it in this browser.</p>
      <a href="/forgot-password" className="underline">Send a new reset link</a>
    </main>
  );
}

lib/supabase/server.ts

import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

// One client per request. Same file as on the Supabase login page guide.
export async function createClient() {
  const cookieStore = await cookies();

  return createServerClient(process.env.NEXT_PUBLIC_SUPABASE_URL!, process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!, {
    cookies: {
      getAll() {
        return cookieStore.getAll();
      },
      setAll(cookiesToSet) {
        try {
          cookiesToSet.forEach(({ name, value, options }) => cookieStore.set(name, value, options));
        } catch {
          // Called from a Server Component: safe to ignore when middleware refreshes the session
        }
      },
    },
  });
}

Good to know

Four steps: the forgot password page asks Supabase to send the email, the email links to /auth/confirm on your own site, that route trades the token_hash for a session cookie with verifyOtp, and the change password page calls updateUser with the new password.
Change the Reset Password email template first. The default template links to Supabase's verify endpoint, which works for the browser-only flow. With @supabase/ssr the link has to carry the token_hash to your route, which is the template above, copied from Supabase's password guide.
redirectTo has to be on your Redirect URLs list (Authentication > URL Configuration), and Site URL has to be your real domain, since the template builds the link from it. On localhost, set Site URL to http://localhost:3000 while you test.
The forgot password page always says the same thing. Supabase sends nothing for an unknown email and still returns no error, so your page can't leak who has an account either.
Supabase's built-in email service is for trying things out: its docs give it a limit of 2 emails per hour. Set up your own SMTP before real users depend on reset emails.
The /auth/confirm route only follows next values that start with one slash, so a link can't send people to another site. Supabase's own example skips that check.
Session refresh still needs the middleware from Supabase's Next.js server-side auth guide (middleware.ts on Next.js 15). The Supabase login page guide, linked below, has the client files.

Spotlight Lamp Login is the sign-in page: a desk lamp lights the card, a wrong password shows Supabase's own error under the field, and a good one floods the screen with the app. Its onSignIn prop gets the email and password and waits for your answer, so supabase.auth.signInWithPassword drops straight in.
What it doesn't do: there's no forgot password, email sent or new password screen in the piece. Those are the three plain pages above. The card does have a Forgot password? link, but it ships pointing at #forgot, and there's no prop for it. It's one line in SpotlightLampLogin.tsx, which is your file after you copy it from the zip, so change the href to /forgot-password.
After the new password is saved, the user is already signed in, so the action above redirects to /dashboard. If you'd rather they sign in again on the lamp, call supabase.auth.signOut() in the action and redirect to /login instead.
We built this page with the real component on October 26, 2026: the edited link rendered as href="/forgot-password" in a local next start. Passing a forgotHref prop instead fails to type-check, because the component has no such prop.

app/login/page.tsx

"use client";
import { useRouter } from "next/navigation";
import SpotlightLampLogin from "@/components/SpotlightLampLogin";
import { createClient } from "@/lib/supabase/client";

// The lamp's "Forgot password?" link now goes to /forgot-password (the one-line edit below).
export default function LoginPage() {
  const router = useRouter();
  const supabase = createClient();

  return (
    <div className="h-dvh">
      <SpotlightLampLogin
        autoplayDemo={false}
        onSignIn={async (email, password) => {
          const { error } = await supabase.auth.signInWithPassword({ email, password });
          return error ? { ok: false, message: error.message } : { ok: true };
        }}
        onSuccess={() => {
          router.push("/dashboard");
          router.refresh();
        }}
      />
    </div>
  );
}

components/SpotlightLampLogin.tsx (the one-line edit)

// components/SpotlightLampLogin.tsx (your copy from the zip), line 134. The link ships as a placeholder:
<a href="#forgot">Forgot password?</a>

// Point it at the page from this guide:
<a href="/forgot-password">Forgot password?</a>

Supabase reset password: auth session missing

AuthSessionMissingError ("Auth session missing!") comes from updateUser when there is no signed-in user on that request. updateUser only works for a signed-in user, and in a reset flow the only session is the one the link created.
The usual causes: the change password page was opened directly instead of through the email link; the link went through Supabase's verify endpoint to a page that never stored the session on the server; or, with the default ?code= link, the person opened the email in a different browser from the one that asked for the reset. The code exchange needs a cookie that only that first browser has.
The token_hash template fixes the last two, because verifyOtp runs in your route and sets the session cookie on the response, whichever browser opens the link. The page above also checks getClaims() first and sends people without a session to the error page instead of showing a form that can't work.

Supabase reset password link not working

"Email link is invalid or has expired" (error code otp_expired) right after the email arrives usually means something opened the link before the person did. Supabase's email template docs name the cause: some mail providers, Microsoft Defender's Safe Links for example, prefetch links to scan them, and a reset link only works once.
Supabase's two documented fixes: put the 6-digit {{ .Token }} in the email and have people type it on a page that calls verifyOtp with the email, token and type recovery, or link to a page of yours with a button that opens the real link, so a scanner's GET doesn't use it up.
Other things to check: the link points to your Site URL, so a wrong Site URL sends people to the wrong domain; redirectTo must be on the Redirect URLs list or Supabase falls back to the Site URL; and email tracking in an outside email provider rewrites links, which Supabase recommends turning off.
Each reset request sends a new email. Only the newest link is worth testing.

Change password while signed in

The same updateUser call works for a signed-in user on an account settings page, no email needed. Supabase's password guide adds one option for that case: pass current_password next to password and Supabase checks the old one first. It needs supabase-js 2.102.0 or newer.
Two error codes worth their own message, both in the action above: same_password when the new password matches the old one, and weak_password when it fails the rules you set under Authentication > Providers > Email. weak_password's message says what's missing, so showing it as is helps.

Install

Copy from the zipPut react/src/components + react/src/data into src/, then npm i @supabase/supabase-js @supabase/ssr.
Or ask your AIPaste PROMPT.md into Cursor, Lovable or v0.

Props

onSignIn: supabase.auth.signInWithPassword; return { ok: false, message } to show Supabase's error
onSuccess: route to your app after the lamp floods the screen
autoplayDemo: false in a real app
Forgot password? link: not a prop: edit the href in SpotlightLampLogin.tsx to /forgot-password

How qodesign compares

qodesign vs Magic UIMagic UI is best for: landing pages built with shadcn/ui.
qodesign vs Aceternity UIAceternity UI is best for: teams building many marketing pages who want one big library.

All comparisons, with prices read on each library's own site.

From the blog: Accessible Login Form in React: Labels, Errors, Motion

Questions

Why use token_hash instead of the default reset link?

With @supabase/ssr, the default link either lands on a page that never stores the session on the server, or exchanges a ?code= that only works in the browser that asked for the reset. A token_hash link goes to your /auth/confirm route, verifyOtp sets the session cookie there, and the change password page reads it on the server.

Does resetPasswordForEmail tell me if the email exists?

No. Supabase sends no email for an unknown address and still returns without an error, so nobody can probe for accounts. Show the same message either way, as the page above does.

How do I fix auth session missing on the update password page?

Make sure the page is reached through the email link, that the link goes to your /auth/confirm route (the token_hash template), and that the route calls verifyOtp with a server client that sets cookies. Then check getClaims() on the page before showing the form.

Does the Spotlight Lamp Login include a reset password screen?

No. It's the sign-in page only. Its Forgot password? link is a #forgot placeholder you point at /forgot-password, and the reset pages are the plain ones on this page.

Does the reset flow work in Next.js?

Yes, as a client component. Keep "use client" at the top of the file that renders it, as in the snippet above. App Router and Pages Router both work.

Can Cursor or v0 add it for me?

Yes. Each download has a PROMPT.md. Paste it into Cursor, Lovable, v0 or Claude Code and it fits the piece into your app.

Can I use it in client work?

Yes, in personal and client projects. You can't resell the code itself as a kit.

Supabase reset password and forgot password in the Next.js App Router

The Supabase reset flow in the App Router

Good to know

Where the Spotlight Lamp Login fits

Supabase reset password: auth session missing

Supabase reset password link not working

Change password while signed in

Install

Props

How qodesign compares

Questions

The Supabase reset flow in the App Router

Good to know

Where the Spotlight Lamp Login fits

Supabase reset password: auth session missing

Supabase reset password link not working

Change password while signed in

Install

Props

How qodesign compares

Questions