Skip to main content
UsernameValidationResult
​
useUsernameValidation
UsernameValidationResult
React hook for validating a username against the current Auth0 username policy.This hook checks the provided username against all configured validation rules and returns a structured result describing whether it passes. Optionally, it can send validation errors to the global error manager so that UI components observing the username field can automatically display or react to these errors.

​
Key Features

  • Policy-aware validation — checks the username against the tenant’s configured Auth0 username policy rules.
  • Error manager integration — optionally surfaces validation failures to form error components automatically.
  • Optimized recomputation — only recomputes when username or options.includeInErrors change.

​
Parameters

​
username
string
The username string to validate.
​
options
{ includeInErrors?: boolean }
Optional configuration for the hook.

​
Returns

UsernameValidationResultA UsernameValidationResult object with:
  • isValid — true if the username satisfies all configured rules.
  • errors — an array of per-rule validation errors with code, message, and isValid.

​
Supported Screens

  • signup
  • signup-id
Example
import { useUsernameValidation } from "@auth0/auth0-acul-react/signup";

export function UsernameField() {
  const { isValid, errors } = useUsernameValidation(username, { includeInErrors: true });

  return (
    <div>
      <input
        value={username}
        onChange={e => setUsername(e.target.value)}
        aria-invalid={!isValid}
      />

      {!isValid && (
        <ul>
          {errors.map(err => (
            <li key={err.code}>{err.message}</li>
          ))}
        </ul>
      )}
    </div>
  );
}

​
Remarks

  • When includeInErrors is enabled, the hook automatically updates the errors to the error-store which can be consumed by useErrors hook.
  • The hook only recomputes when username or options.includeInErrors change.
  • Call useUsernameValidation at the top level of your component; do not call it conditionally or inside event handlers.
  • The import path must match the screen — use signup or signup-id accordingly.