Username Availability Field

ProNew

A username field that checks the rules as you type, asks the server if the name is free after a pause, announces the result and offers alternatives when it is taken. Use this when people choose a unique handle.

Customize

Derived from this item’s props table, because it declares no controls of its own. This item has no standalone playground, so changes update the code, the share link and the AI prompt.

value

defaultValue

minLength` / `maxLength1

debounceMs400

label

Guide and examples

When to use it

Use it for sign-up, workspace URLs and handles, where finding out a name is taken only after pressing Submit costs people their patience.

Do not use it when uniqueness is checked privately for security reasons (it would reveal which accounts exist). Check on submit there.

Installation

This item is part of tealmac UI Pro

The source for this item installs with a Pro licence key. Log in with your key to see the install command, or read the Pro setup page.

Props

Prop	Type	Default	Description
`check`	`(username, { signal }) => Promise<boolean>`	-	Resolves `true` when the name is free.
`value`	`string`	-	The username (controlled).
`defaultValue`	`string`	`""`	Initial username.
`onValueChange`	`(value: string) => void`	-	Runs on every change (lower-cased).
`onStatusChange`	`(status) => void`	-	`empty`, `invalid`, `checking`, `available`, `taken` or `error`.
`suggest`	`(username) => string[]`	adds numbers	Alternatives when the name is taken.
`minLength` / `maxLength`	`number`	`3` / `20`	Length rules.
`debounceMs`	`number`	`400`	Wait after typing before asking the server.
`label`	`string`	`Username`	Visible label.

Accessibility

The input has a visible label; the message under it is linked with aria-describedby and is a polite role="status" line.
Rule violations read as specific sentences (Use 3 to 20 characters, Start with a letter, Letters, numbers and underscores only).
aria-invalid is set while the name breaks a rule or is taken.
Suggestions are buttons in the tab order after the field; choosing one runs the check again.

Testing

The pattern ships with a Testing Library test (username-availability-field.test.tsx) that covers the rule messages, the debounced check, a taken name with suggestions and an error from the server.

Guide and examples

When to use it

Use it for sign-up, workspace URLs and handles, where finding out a name is taken only after pressing Submit costs people their patience.

Do not use it when uniqueness is checked privately for security reasons (it would reveal which accounts exist). Check on submit there.

Installation

This item is part of tealmac UI Pro

The source for this item installs with a Pro licence key. Log in with your key to see the install command, or read the Pro setup page.

Props

Prop	Type	Default	Description
`check`	`(username, { signal }) => Promise<boolean>`	-	Resolves `true` when the name is free.
`value`	`string`	-	The username (controlled).
`defaultValue`	`string`	`""`	Initial username.
`onValueChange`	`(value: string) => void`	-	Runs on every change (lower-cased).
`onStatusChange`	`(status) => void`	-	`empty`, `invalid`, `checking`, `available`, `taken` or `error`.
`suggest`	`(username) => string[]`	adds numbers	Alternatives when the name is taken.
`minLength` / `maxLength`	`number`	`3` / `20`	Length rules.
`debounceMs`	`number`	`400`	Wait after typing before asking the server.
`label`	`string`	`Username`	Visible label.

Accessibility

The input has a visible label; the message under it is linked with aria-describedby and is a polite role="status" line.
Rule violations read as specific sentences (Use 3 to 20 characters, Start with a letter, Letters, numbers and underscores only).
aria-invalid is set while the name breaks a rule or is taken.
Suggestions are buttons in the tab order after the field; choosing one runs the check again.

Testing

The pattern ships with a Testing Library test (username-availability-field.test.tsx) that covers the rule messages, the debounced check, a taken name with suggestions and an error from the server.