useErrors

useErrors(options?: UseErrorOptions) · UseErrorsResult

React hook for reading and managing errors in ACUL (Advanced Customization of Universal Login). It groups errors into three kinds:

• auth0 — errors returned by Auth0 or your own backend.
• validation — errors from client-side validation (e.g., invalid form input).
• configuration — errors caused by incorrect integration or SDK misuse.

Key Features

• Unified error store — surfaces auth0, validation, and configuration errors from a single hook.
• Flexible filtering — query errors by kind, field, or a combination of both.
• Dismiss controls — remove individual errors or clear all at once.

Parameters

options · UseErrorOptions

Optional configuration for the hook.

Show properties

includeDevErrors · boolean

When true, includes development-specific error details in the error list. Defaults to false.

Returns

UseErrorsResult

A UseErrorsResult object containing:

• errors — the full error list of type ErrorsResult, with helpers:
  • errors.byType(type, filter?) — filter by error type and optionally by field.
  • errors.byField(field, filter?) — filter by field and optionally by type.
• hasError — true if any error is currently present.
• dismiss(id) — remove a specific error by its ID.
• dismissAll() — clear all tracked errors.

Supported Screens

• The useErrors hook is available on every ACUL screen.

Example

import { useErrors } from "@auth0/auth0-acul-react";

export function SignupForm() {
  const { errors, hasError, dismiss, dismissAll } = useErrors();

  return (
    <div>
      {hasError && (
        <div className="mb-4">
          {errors.byType("auth0").map(err => (
            <div key={err.id} className="text-red-600">
              {err.message}
              <button onClick={() => dismiss(err.id)}>Dismiss</button>
            </div>
          ))}
        </div>
      )}

      <button onClick={dismissAll}>Clear All Errors</button>
    </div>
  );
}

In addition to rendering messages, you can filter by field or kind:

console.log(errors.byType('validation')); // all validation errors
console.log(errors.byType('validation', { field: 'username' })); // validation errors for field 'username'
console.log(errors.byField('username')); // all errors for field 'username'
console.log(errors.byField('username', { type: 'auth0' })); // auth0 errors for field 'username'

Remarks

• useErrors is not screen-scoped — import it directly from @auth0/auth0-acul-react.
• Call useErrors at the top level of your component; do not call it conditionally or inside event handlers.
• Use includeDevErrors: true during development to surface SDK misuse errors; disable it in production.