> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-docs-event-stream-action-templates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# useUsernameValidation

```tsx theme={null}
useUsernameValidation(
  username: string,
  options?: { includeInErrors?: boolean },
): UsernameValidationResult
```

<ParamField body="useUsernameValidation" type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UsernameValidationResult">UsernameValidationResult</a></span>}>
  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

  <ParamField body="username" type="string">
    The username string to validate.
  </ParamField>

  <ParamField body="options" type="{ includeInErrors?: boolean }">
    Optional configuration for the hook.

    <Expandable title="properties">
      <ParamField body="includeInErrors" type="boolean">
        When `true`, validation errors are stored in the global error manager under the `username` field. Defaults to `false`.
      </ParamField>
    </Expandable>
  </ParamField>

  ## Returns

  [`UsernameValidationResult`](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UsernameValidationResult)

  A [UsernameValidationResult](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/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`

  ```tsx Example theme={null}
  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.
</ParamField>