Skip to main content

Three-stage reset flow

Overview​

The password reset process moves through three stages: request, reset, and completion. Each stage has its own form and purpose.

For developers

See Advanced (Developers) for technical details about URL parameters, hooks, and workflow customization.

The three stages​

Stage 1: Request​

What happens: User enters their email address or username to request a password reset.

What the user does:

  1. Navigate to the password reset page
  2. Enter email address or username
  3. Click submit

What happens:

  • Plugin checks if the email/username exists
  • Sends an email with a reset link
  • Shows success message or error

Possible messages:

  • Success: "An email has been sent. Please check your inbox."
  • Error: "That email address is not recognised."

Stage 2: Reset​

What happens: User clicks the reset link in their email and enters a new password.

What the user does:

  1. Click the reset link in the email
  2. Enter new password (twice)
  3. Watch validation indicators turn green as requirements are met
  4. Click submit

What happens:

  • Plugin checks if the reset link is valid (expires after 24 hours)
  • Validates the new password meets requirements
  • Updates the password
  • Shows completion page

Possible messages:

  • Success: Redirect to completion page
  • Error: "That key has expired. Please reset your password again."
  • Error: "The passwords don't match."
  • Error: Password requirements not met (shown with red indicators)

Stage 3: Completion​

What happens: User sees a success message and login link after successfully changing their password.

What the user does:

  1. Read the success message
  2. Click the login link

What happens:

  • Shows success message
  • Provides login link
  • User can now log in with new password

How to customize​

Change form appearance: Copy template files to your theme (see Template override system)

Modify email content: Use Settings > Frontend Reset Password > General tab (see Email customization)

For developers: See Advanced (Developers) for hooks, filters, and URL parameters

Common flow issues​

User stuck at Stage 1​

Symptom: Email never arrives, user can't proceed to Stage 2.

Cause: Email delivery failure (common on localhost).

Solution: See Email not sending troubleshooting.

Stage 2 shows "key expired" error​

Symptom: Clicking email link shows expired key error.

Cause: Reset link is older than 24 hours or user requested multiple resets.

Solution: Request a new reset email. Only the most recent link works.

Stage 2 redirects to wp-login.php​

Symptom: Email link goes to WordPress default login page instead of custom page.

Cause: Reset Password Page setting not configured correctly.

Solution: Verify Settings > Frontend Reset Password > Reset Password Page is set to your custom page.

What's next​