ForgotPasswordForm

Overview

ForgotPasswordForm collects an email address and calls useForgotPassword to request a reset link. Pair it with ResetPasswordForm on the page your reset URL opens.

Configure the reset-link path in the dashboard

The path embedded in the reset email (e.g. /reset-password) is set per-app under Dashboard → App Settings → Reset password path. SimpleAuth prepends your configured App base URL to that path when building the link. If either setting is blank the email contains only the raw token for manual entry.

Preview

Interactive preview requires JavaScript.

Install

npx @simpleauthjs/react add forgot-password --style minimal

The install snippet uses --style minimal. You can also use --style modern. Style variants compares those two in the live preview. Run npx @simpleauthjs/react add --help for every --style slug the CLI accepts.

Props

Name	Type	Required	Default	Description
`onSuccess`	`() => void`	No	`undefined`	Called after the reset email request succeeds.
`appName`	`string`	No	`undefined`	Mentioned in success copy when set.
`signInHref`	`string`	No	`undefined`	Footer “Sign in” link when `onSwitchToSignIn` is not set.
`onSwitchToSignIn`	`() => void`	No	`undefined`	Footer button for sign-in; takes precedence over `signInHref`.

Usage

import { ForgotPasswordForm } from "@/components/simpleauth"

export default function ForgotPasswordPage() {
  return <ForgotPasswordForm appName="Acme" onSuccess={() => console.info("email sent")} />
}

Source

components/simpleauth/hooks/use-forgot-password.ts

"use client"

import { useState } from "react"
import { SimpleAuthError, type SuccessResponse } from "@simpleauthjs/core"
import { useSimpleAuthClient } from "../provider"

function getErrorMessage(error: unknown) {
  if (error instanceof SimpleAuthError) {
    return error.message
  }

  if (error instanceof Error) {
    return error.message
  }

  return "Unable to send reset email."
}

export function useForgotPassword() {
  const auth = useSimpleAuthClient()
  const [isLoading, setIsLoading] = useState(false)
  const [error, setError] = useState<string | null>(null)
  const [data, setData] = useState<SuccessResponse | null>(null)

  async function forgotPassword(email: string) {
    setIsLoading(true)
    setError(null)

    try {
      const response = await auth.forgotPassword({ email: email.trim() })
      setData(response)
      return response
    } catch (requestError) {
      setData(null)
      setError(getErrorMessage(requestError))
      throw requestError
    } finally {
      setIsLoading(false)
    }
  }

  function reset() {
    setData(null)
    setError(null)
    setIsLoading(false)
  }

  return {
    forgotPassword,
    data,
    error,
    isError: Boolean(error),
    isLoading,
    isSuccess: Boolean(data?.success),
    reset,
  }
}

Customisation

Owned by you

Files live at components/simpleauth/ui/forgot-password-form.tsx and components/simpleauth/styles/forgot-password-form.css.

ForgotPasswordForm

On this page