# Email Input

> A React email input for one address or a list of recipients, with domain completion, typo hints, contact suggestions and validation.

- Type: React component (Inputs)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add email-input`
- Docs: https://wingo-ui.com/components/email-input

## Interaction

One address: type a name and after the @ a list completes the domain (emma@gm offers emma@gmail.com); Arrow Down and Up move through it, Enter or Tab takes the highlighted address, Escape closes it. Leaving the field checks the address: a malformed one shows the error, a likely typo shows "Did you mean emma@gmail.com?" with the fix as a button, and a valid one gets a green check. The error goes away as soon as the text is fixed. With multiple, every address becomes a chip with the person's initials or photo: type and press Enter, a comma, a semicolon or a space after a full address; pick a contact from the list by name or address; or paste a whole list like Emma Carter <emma@acme.com>, liam@acme.com; olivia@acme.com and every entry becomes a chip with its name, duplicates once (the existing chip pulses). A bad address stays as a red chip and the field says why; a likely typo turns its chip amber and the hint fixes it in one tap. Backspace in the empty text brings the last chip back as text to fix. Arrow Left at the start of the text moves onto the chips: Left and Right walk, Home and End jump, Delete or Backspace removes, Enter or F2 (or a double-click, or a second tap) edits, Cmd/Ctrl+C copies Name <address>, Escape returns to the text. Cmd/Ctrl+Enter adds the text and submits the form. On a phone the keyboard shows the email layout, text is 16px so iOS never zooms, the chip × buttons have a large touch area and the list stays in the page above the keyboard.

## Installation

```bash
npx wingo-ui@latest add email-input
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/email-input` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/ui/email-input.tsx`

npm dependencies: `npm i motion lucide-react`

Wingo UI dependencies (installed automatically):

- [Avatar](https://wingo-ui.com/components/avatar) ([Markdown](https://wingo-ui.com/components/avatar.md))
- [Badge](https://wingo-ui.com/components/badge) ([Markdown](https://wingo-ui.com/components/badge.md))
- [Field](https://wingo-ui.com/components/field) ([Markdown](https://wingo-ui.com/components/field.md))
- [Listbox](https://wingo-ui.com/components/listbox) ([Markdown](https://wingo-ui.com/components/listbox.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [Text match](https://wingo-ui.com/components/text-match) ([Markdown](https://wingo-ui.com/components/text-match.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
import { useState } from "react"
import { EmailInput, type EmailContact } from "@/components/ui/email-input"

const CONTACTS: EmailContact[] = [
  { name: "Emma Carter", email: "emma@acme.com" },
  { name: "Liam Brooks", email: "liam@acme.com" },
  { name: "Olivia Bennett", email: "olivia.bennett@gmail.com" },
]

export function NewMessage() {
  const [from, setFrom] = useState("")
  const [to, setTo] = useState<string[]>(["emma@acme.com"])

  return (
    <div className="flex flex-col gap-4">
      <EmailInput label="Your email" value={from} onValueChange={setFrom} name="from" required />
      <EmailInput multiple label="To" value={to} onValueChange={setTo} contacts={CONTACTS} name="to" clearable />
    </div>
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `multiple?` | `boolean` | `false` | A list of recipients as chips; value becomes string[]. Off, the field holds one address as a string. |
| `label?` | `ReactNode` | `""` | Renders the field anatomy around the box: the label above it, linked to the text input. |
| `description?` | `ReactNode` | `""` | Helper text under the box. A typo hint takes its place while it shows; at the limit labels.limit(max) does when you pass none. |
| `error?` | `ReactNode` | `""` | Replaces the description with the animated error and marks the field invalid. Without it the field shows its own checks. |
| `required?` | `boolean` | `false` | The red mark after the label and required / aria-required on the text input. |
| `invalid?` | `boolean` | `false` | The invalid look and aria-invalid without a message. |
| `disabled?` | `boolean` | `false` | Dims the field, blocks typing and hides the × on chips. |
| `readOnly?` | `boolean` | `false` | The value stays visible and selectable but cannot change; chips stay focusable and copyable. |
| `placeholder?` | `string` | `"name@example.com"` | Hint text while empty. Multiple mode defaults to Add people by name or email. |
| `value?` | `string \| string[]` |  | The address (single) or the addresses (multiple), controlled; pair it with onValueChange. |
| `defaultValue?` | `string \| string[]` | `""` | The starting value while uncontrolled: a string in single mode, a list in multiple mode. A form reset returns to it. The playground takes a comma-separated list in multiple mode. |
| `onValueChange?` | `(value: string \| string[]) => void` |  | Fires with the new text on every keystroke (single), or with the new list after every add, remove, fix and clear (multiple). |
| `onChange?` | `(event: ChangeEvent<HTMLInputElement>) => void` |  | The native change event of the text input, untouched. |
| `contacts?` | `EmailContact[]` | `"[]"` | People suggested while typing, matched by name, address or keywords (case and diacritics ignored). Chips of a known address show the name and photo. |
| `domains?` | `string[]` | `"EMAIL_DOMAINS"` | Completed after the @ and used for typo hints (gmail.com, outlook.com, yahoo.com, icloud.com...). [] turns both off. |
| `allowedDomains?` | `string[]` |  | Only addresses at these domains are accepted (labels.domain names them); they also become the completions after the @. |
| `validate?` | `(email: string) => (string \| boolean)` |  | Extra rules after the format check: false marks the address invalid with the default message, a string with that message. |
| `suggestTypos?` | `boolean` | `true` | Did you mean emma@gmail.com? under the field for a likely typo in the domain (gmial.com, gmail.con, gmail without .com). |
| `showValidIcon?` | `boolean` | `true` | Single mode: a green check at the end once the address is valid and the field was left. |
| `clearable?` | `boolean` | `false` | A clear button while there is a value: the text (Escape clears too) or every recipient. |
| `max?` | `number` | `0` | Multiple mode: the most recipients. At the limit the text hides and the description reads labels.limit(max). 0 means no limit. |
| `invalidEntries?` | `"keep" \| "reject"` | `"keep"` | Multiple mode: keep a bad address as a red chip to fix later (like a mail app), or leave it in the text, shake and show why. |
| `showAvatars?` | `boolean` | `true` | Multiple mode: the contact's photo or colored initials in each chip; the chips turn into pills. |
| `leftIcon?` | `ReactNode` | `"<Mail />"` | Single mode: the leading icon; null hides it. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Height 32 / 40 / 48px (md 44px on touch), 20 / 24 / 28px chips, 13 / 14 / 15px text (16px on phones). The multiple box grows as chips wrap. |
| `variant?` | `"soft" \| "outline" \| "underline" \| "ghost"` | `"soft"` | The box look shared with every input. |
| `radius?` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | `"md"` | Box corners scaled with the size. |
| `chipVariant?` | `"soft" \| "outline" \| "solid"` | `"soft"` | Multiple mode: the Badge variant of the chips. |
| `tone?` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Multiple mode: the color of valid chips. Bad addresses are always danger, likely typos warning. |
| `color?` | `string` | `""` | Any CSS color for valid chips; replaces the tone. |
| `name?` | `string` | `""` | Single mode: the input's name. Multiple mode: one hidden input per address, so FormData.getAll(name) returns the list. |
| `labels?` | `Partial<EmailInputLabels>` |  | Copy merged over the English defaults: invalid, invalidEntry(email), invalidCount(n), domain(domains), didYouMean(fix), useSuggestion(email), recipient(label, email), remove, added, removed, duplicate, limit(max), copied(email), clear, suggestions. |
| `onReject?` | `(email: string, reason: "invalid" \| "duplicate" \| "limit" \| "domain") => void` |  | Called for every address that was turned away or flagged. |
| `fieldProps?` | `Partial<FieldProps>` |  | Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel. |
| `ref?` | `RefObject<HTMLInputElement \| null> or (node) => void` |  | The text input. Every other native prop lands there too: autoFocus, autoComplete, enterKeyHint, onBlur, onKeyDown (runs first), aria-*, data-*. |
| `classNames?` | `Partial<Record<"field" \| "label" \| "description" \| "error" \| "counter" \| "root" \| "box" \| "icon" \| "input" \| "chip" \| "valid" \| "clear" \| "hint" \| "suggestions" \| "list" \| "option", string>>` |  | Extra classes for the parts: the field anatomy, the box, the icon, the text input, each chip, the valid check, the clear button, the typo hint and the suggestions panel. |
| `className?` | `string` |  | Classes for the outermost element: the Field root when there is a label, description or error, else the email input root. |

## Parts

### isValidEmail (function)

The format check the field uses: one @, a sensible local part and a domain with a TLD of 2 or more letters, 254 characters at most.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `email?` | `string` |  | The address to check. |
| `returns?` | `boolean` |  | true when the format is valid. |

### normalizeEmail (function)

Trims, drops mailto: and angle brackets and lowercases the domain. The field runs it on every address it keeps.

### suggestEmailFix (function)

The typo check behind the hint: emma@gmial.com gives emma@gmail.com, liam@acme.con gives liam@acme.com, and null when nothing looks wrong.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `email?` | `string` |  | The address to check. |
| `domains?` | `string[]` | `"EMAIL_DOMAINS"` | The known domains to compare against. |
| `returns?` | `string \| null` |  | The corrected address, or null. |

### parseEmailList (function)

Splits a pasted list on commas, semicolons, tabs and new lines (quotes and <> respected) into { email, name? } entries: "Emma Carter <emma@acme.com>, liam@acme.com".

### EMAIL_DOMAINS (constant)

The default domains completed after the @ and used for typo hints: gmail.com, outlook.com, yahoo.com, icloud.com, hotmail.com, proton.me and more.

### EmailContact (type)

A suggested person: { email, name?, avatar?, keywords? }.

### EmailEntry (type)

One parsed entry from parseEmailList: { email, name? }.

### EmailInputLabels (type)

Every string the field shows or announces, for the labels prop.

## Examples

- **Sign up**: One address with domain completion, a typo hint, the valid check and a form submit.
- **Compose**: To and Cc with contacts suggested by name or address.
- **Paste a list**: invalidEntries keep (red chips) next to reject (text stays and shakes).
- **Company only**: allowedDomains, max={5} and brand chips in a pill box.
- **Styles**: Sizes, box variants, chip variants, tones, no avatars and a custom color.
- **States**: A server error, read only and disabled.

## See also

- [Tag Input](https://wingo-ui.com/components/tag-input) ([Markdown](https://wingo-ui.com/components/tag-input.md))
- [Input](https://wingo-ui.com/components/input) ([Markdown](https://wingo-ui.com/components/input.md))
- [Field](https://wingo-ui.com/components/field) ([Markdown](https://wingo-ui.com/components/field.md))
- [Avatar](https://wingo-ui.com/components/avatar) ([Markdown](https://wingo-ui.com/components/avatar.md))
- [Multi Select](https://wingo-ui.com/components/multi-select) ([Markdown](https://wingo-ui.com/components/multi-select.md))

---

Canonical: https://wingo-ui.com/components/email-input
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt
