Authentication/guides/Password Recovery

Request a Reset Link

Provide a recovery form and understand preview mail versus WordPress delivery.

On This Page

Request a password reset link

Password recovery starts with an account identifier, usually a username or email. WordPress sends a link that allows its owner to choose a new password. Requesting that link does not change the password or sign the visitor in.

Two pages, two jobs

The recovery page requests a link. The reset page receives that link and collects a new password. Despite its name, WpPasswordResetForm provides the first step: requesting the link.

Flowchart

Rendering diagram...

Add the recovery form

src/components/PasswordRecovery.tsx

1import { WpAuthProvider, WpPasswordResetForm } from "@forgewp/auth"
2
3export default function PasswordRecovery() {
4  return (
5    <WpAuthProvider>
6      <WpPasswordResetForm className="max-w-md" />
7    </WpAuthProvider>
8  )
9}

The form accepts className and an optional onSuccess callback. It delegates to the Auth recovery action, so its local preview creates the same mock link as a custom interface using that action.

For custom controls, call forgotPassword(login) from useWpAuth(). It returns a boolean promise. Use loading to prevent repeat submissions and render error when it returns false. Trim the account identifier before calling it; keep the visitor's input available for correction.

Compare the environments

Table · 3 columns


Step	Local preview	Installed WordPress theme
Find an account	Match mock username or email	Ask WordPress to recover the account
Produce a link	Store a mock token and request a preview email-log entry	Use WordPress recovery mail and its reset key
Where to look	Preview email log and mock account configuration	The account owner's inbox and configured mail transport
What success proves	The simulation accepted the request	WordPress accepted the recovery request

Test with a known preview account

Ensure the mock user exists before requesting a link. Copy the reset link from the preview email log into the same browser so its local mock token is available.

An HTTP success does not prove inbox delivery. WordPress-reported recovery or mail errors are exposed through the hook. The current endpoint can also expose account-not-found errors; it does not promise an identical response for every account identifier.

Configure the recovery email

Edit the installed defaults at Settings → ForgeWP Auth. Developers can provide initial text through auth.emails.passwordReset.subject and .body. The body supports {username} and {reset_url}.

The generated email points to /reset-password?key=...&login=... on the configured frontend. Provide that route in the theme. An email template does not create the destination page.

Table · 2 columns


Situation	Helpful response
Identifier is missing	Ask the visitor to enter username or email
Recovery request fails	Render the action error and allow retry
Request succeeds	Ask the visitor to check the appropriate email destination
Link is old or invalid	Offer another recovery request

Continue with Choose a New Password.