# Input

A single-line text field with sm/default/lg sizes, an optional label, helper or error text, leading and trailing content, and a password reveal button.

- Category: Core Elements
- Page: https://wunderui.com/components/input
- Tier: Free

## Install

```bash
npx wunderui-cli add input
```

## Import

```tsx
import { Input, InputFieldProps, InputProps, PasswordField, TextField } from "@/components/ui/input"
```

## Minimal usage

Then use it:

```tsx
import { Input } from "@/components/ui/input"

export function Email() {
  return <Input label="Work email" type="email" placeholder="name@company.com" />
}
```

Expected result: You see the label Work email above a white field with a grey placeholder. Clicking the label focuses the field and turns its border indigo.

## Usage

```tsx
import { Field, FieldDescription } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <Field>
      <Label htmlFor="email" className="mb-1">
        Work email
      </Label>
      <Input id="email" type="email" placeholder="name@company.com" />
      <FieldDescription>We send receipts to this address.</FieldDescription>
    </Field>
  )
}
```

## When to use

### Use Input for

- One line of free text, such as a name, an email address or a search term
- A value with a known format, such as a URL, an amount or a card number
- A field with something attached, such as an icon, a unit, a shortcut or a copy button

### Use something else

- [Textarea](https://wunderui.com/components/textarea) for text over several lines, such as a message or feedback
- [Number Field](https://wunderui.com/components/number-field) for a quantity with plus and minus buttons
- [Select](https://wunderui.com/components/select) for a choice from a short list of known options
- [OTP Field](https://wunderui.com/components/otp-field) for a one-time code typed in separate cells

## Keyboard

An input is one tab stop and takes the keys of a native text field: typing, selecting and system shortcuts are the browser's.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into and out of the field. A disabled field is skipped; a read-only field keeps its place in the order. |
| `Enter` | Sends the form that holds the field. If a required field is empty or wrong, focus goes to the first one and its message shows in a tooltip. |
| `Escape` | In a field with `type="search"` the browser clears what was typed. In other types it does nothing. |
| `Tab` or `Space` or `Enter` | With `revealable`, Tab moves from the field to the show-or-hide button; Space or Enter shows or hides the password. Focus stays on the button. |

## Behavior

What the input does itself, and what it leaves to the page.

- **A native element:** Input renders a native input, so every attribute works (type, name, value, autocomplete, pattern, required and the rest), and refs reach the element.
- **Controlled or not:** Pass a value and change handler to own the text, or a default value to let the field keep it. Inside a Field, the description and error are linked to the input for assistive technology.
- **Size and density:** Size sets the height: 32, 36 or 40 px at the default density, 36, 44 or 52 px in comfortable density. They match the Button heights, so a field and a button line up.
- **Label:** A label joins the text to the field, and when the field is disabled the label and helper dim with it. A field without a visible label takes an aria-label and renders the bare input.
- **One component, two shapes:** With no field props, Input renders just the bare input; with any, a column of label, field and message. Props count by being present, so toggling an error never swaps the DOM or drops focus.
- **Invalid:** An error turns the border and focus ring red and shows its message in place of the helper. The fill stays white, and both messages are linked to the input.
- **Password reveal:** A revealable password field gets a show or hide button in the trailing slot, with a label and icon that follow its state. It does nothing on other types.
- **Validation tooltip:** On submit, the first field that breaks a rule gets focus and the browser's message shows in a WunderUI tooltip, not the browser's bubble. It clears as soon as the person types or leaves the field.
- **Disabled and read-only:** Disabled dims the field to 40 %, skips it in the tab order and leaves it out of the form data. Read-only stays readable, focusable, copyable and submitted, with a subtle fill.
- **Content inside the field:** Leading and trailing put an icon or text inside the field, drawn in an InputGroup that holds the border and focus ring. For a button or shortcut you compose yourself, use InputGroup by hand.
- **Loading:** There is no loading prop. Put a Spinner in the trailing slot, set aria-busy and keep the field editable, so a background check never blocks typing.
- **Motion:** The border colour changes quickly when the pointer enters or the field takes focus. Nothing moves or scales.
- **Reduced motion:** With reduced motion the colour change stays as a short fade, since it isn't movement. The spinner in a loading field stops turning.

## Anatomy

- `Label`: The visible name of the field, joined to the input so a click on it focuses the field. A search field with no room for a label takes an aria-label instead.
- `Input`: The single-line field: a native input with a 1 px border and an 8 px corner, 32, 36 or 40 px high. With content inside it, an InputGroup draws the border and focus ring instead.
- `Leading content`: An icon or short text before the value, such as a mail icon or https://. It isn't interactive and uses the tertiary text colour.
- `Trailing content`: A unit, a shortcut or a small button after the value: USD, a key hint, copy. The reveal option adds a password field's show-or-hide button here.
- `Helper and error text`: A line of 12 px text under the field: the helper with the rule, or the error with what to do. The error replaces the helper, and both are linked to the input for assistive technology.
- `Validation tooltip`: Shows the browser's message for a required, email or pattern rule when the form is submitted, and clears once the user types or leaves the field.
- `PasswordField`
- `TextField`
- `Input`

## Best practices

### When to use

- Use an Input for one line of free text: a name, an email address, a search term. Use a Textarea for several lines, and a Select or Combobox for a choice from a known list.

### Do

- Give every Input a visible label. A placeholder disappears with the first keystroke and is not a name; a search field may use an aria-label.
- Pick the type and autocomplete that match the value (email, password, cc-number). The browser then offers the right keyboard and fills the field in.
- Mark a wrong value with an error and say what to do: Enter an email address like name@company.com, not Invalid input. Keep what the person typed.
- Show the error after the person leaves the field or sends the form, not on the first keystroke. A red field on load reads as a mistake that has not been made yet.
- Keep the label a noun (Work email) and put the rule in the helper below it as a full sentence.
- Make every password field that a person types by hand revealable, and set autocomplete to current-password on sign-in or new-password on sign-up.

### Don't

- Don't import TextField or PasswordField in new code. They are deprecated aliases of Input; use Input with the same props.
- Don't use a placeholder as the label, and don't put the format example only there: it is gone once the field is filled.
- Don't size a field with height classes. Use the size prop (sm, default, lg), so a field and a Button of the same size line up in both densities.
- Don't disable a value people need to read or copy. A read-only field can be focused and copied; a disabled one can't, and it is dimmed.
- Don't use a number input for codes, phone numbers or card numbers. Use text with numeric input mode, so leading zeros survive.

## API reference

### Input

| Prop | Type | Default | Description |
|---|---|---|---|
| error | React.ReactNode |  | The message under the field in the error colour. Sets `aria-invalid`, turns the border and the ring red and replaces `helper`. |
| helper | React.ReactNode |  | A hint under the field in 12 px tertiary text, linked with `aria-describedby`. Replaced by `error` while there is one. |
| label | React.ReactNode |  | The visible name of the field. Joined to the input with `htmlFor`. Any field prop makes the Input render the label row, the field and the message line instead of the bare input. |
| labelTrailing | React.ReactNode |  | A note or a link on the label row, right-aligned, such as `Required` or `Forgot password?`. |
| leading | React.ReactNode |  | An icon or a short text inside the field before the value. The Input is drawn in an `InputGroup`. |
| optional | boolean |  | Adds the tag `(optional)` after the label. It is part of the accessible name. |
| revealable | boolean |  | With `type="password"`, adds a button that shows or hides what was typed. It has `aria-pressed` and the label `Show password` or `Hide password`. Default `false`. |
| size | "default" \| "lg" \| "sm" |  | The height of the field. `sm` is 32 px, `default` 36 px and `lg` 40 px at the default density, and 36, 44 and 52 px in `data-density="comfortable"`. The same heights as the Button sizes `sm`, `md` and `lg`. |
| trailing | React.ReactNode |  | An icon, a unit or a button inside the field after the value. With `revealable`, it sits before the reveal button. |
| wrapperClassName | string |  | Class names for the column around label row, field and message. `className` still goes to the `<input>`. |

Also accepts React.InputHTMLAttributes attributes.

### PasswordField

| Prop | Type | Default | Description |
|---|---|---|---|
| error | React.ReactNode |  | Error message below the field. Sets `aria-invalid` and `aria-describedby`. |
| helper | React.ReactNode |  | Hint below the field. Replaced by `error` while there is one. |
| label | React.ReactNode |  | Visible label. Joined to the control with `htmlFor`. |
| labelTrailing | React.ReactNode |  | A tag or a link on the label row, right-aligned (for example "Forgot password?"). |
| leading | React.ReactNode |  | Content inside the field, before the text (icon, prefix). |
| optional | boolean |  | Adds the "(optional)" tag to the label. |
| revealable | boolean |  | With `type="password"`: adds the button that shows or hides what was typed. |
| size | "default" \| "lg" \| "sm" |  |  |
| trailing | React.ReactNode |  | Content inside the field, after the text (icon, suffix, button). |
| wrapperClassName | string |  | Class names for the wrapper around label, field and message. |

Also accepts React.InputHTMLAttributes attributes.

### TextField

| Prop | Type | Default | Description |
|---|---|---|---|
| error | React.ReactNode |  | Error message below the field. Sets `aria-invalid` and `aria-describedby`. |
| helper | React.ReactNode |  | Hint below the field. Replaced by `error` while there is one. |
| label | React.ReactNode |  | Visible label. Joined to the control with `htmlFor`. |
| labelTrailing | React.ReactNode |  | A tag or a link on the label row, right-aligned (for example "Forgot password?"). |
| leading | React.ReactNode |  | Content inside the field, before the text (icon, prefix). |
| optional | boolean |  | Adds the "(optional)" tag to the label. |
| revealable | boolean |  | With `type="password"`: adds the button that shows or hides what was typed. |
| size | "default" \| "lg" \| "sm" |  |  |
| trailing | React.ReactNode |  | Content inside the field, after the text (icon, suffix, button). |
| wrapperClassName | string |  | Class names for the wrapper around label, field and message. |

Also accepts React.InputHTMLAttributes attributes.

## Examples

### Types: text, email, password, search and number

```tsx
import { Input } from "@/components/ui/input"

export function Example() {
  return (
    <Input label="Full name" placeholder="Nora Lindgren" autoComplete="name" />
  )
}
```

### Sizes: 32, 36 and 40 px

```tsx
import { Input } from "@/components/ui/input"

export function Example() {
  return (
    <Input placeholder="Enter text" />
  )
}
```

### Label, helper and error: text, hint, message, requirement and link

```tsx
import { Input } from "@/components/ui/input"

export function Example() {
  return (
    <Input label="Username" placeholder="nora.lindgren" />
  )
}
```

### Leading and trailing content: icon, prefix, suffix, button and shortcut

```tsx
import { Input } from "@/components/ui/input"
import { Mail } from "lucide-react"

export function Example() {
  return (
    <Input label="Work email" leading={<Mail aria-hidden />} type="email" placeholder="name@company.com" />
  )
}
```

### States: default, hover, focus, filled, disabled, read-only, invalid and loading

```tsx
import { Field, FieldDescription } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <Field>
      <Label htmlFor="email" className="mb-1">
        Work email
      </Label>
      <Input id="email" type="email" placeholder="name@company.com" />
      <FieldDescription>We send receipts to this address.</FieldDescription>
    </Field>
  )
}
```

## In context

### Sign in: two fields and one action

Required fields answer in the WunderUI tooltip when the form is sent empty. The link for a forgotten password sits on the label row.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"

export function Example() {
  const [signedIn, setSignedIn] = useState(false)

  return (
    <form
      className="flex flex-col gap-4"
      onSubmit={(event) => {
        event.preventDefault()
        setSignedIn(true)
      }}
    >
      <Input label="Work email" type="email" placeholder="name@company.com" autoComplete="email" required />
      <Input
        label="Password"
        labelTrailing={
          <a href="/reset-password" className="text-xs font-medium text-text-link hover:underline">
            Forgot password?
          </a>
        }
        type="password"
        revealable
        placeholder="Your password"
        autoComplete="current-password"
        required
      />
      <Button type="submit" variant="gradient">
        Sign in
      </Button>
      <p aria-live="polite" className="min-h-5 text-sm text-text-secondary">
        {signedIn ? "Signed in as the WunderUI workspace." : ""}
      </p>
    </form>
  )
}
```

### Profile: a message that keeps what was typed

The error shows after the person leaves the field and replaces the helper line. Delete the at sign in the email to see it, and the value stays.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Textarea } from "@/components/ui/textarea"
import { Input } from "@/components/ui/input"

const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/

export function Example() {
  const [email, setEmail] = useState("info@wunderui.com")
  const [touched, setTouched] = useState(false)
  const [bio, setBio] = useState("Product lead at WunderUI.")
  const [saved, setSaved] = useState(false)
  const invalid = touched && !EMAIL.test(email)

  return (
    <form
      className="flex flex-col gap-4"
      noValidate
      onSubmit={(event) => {
        event.preventDefault()
        setTouched(true)
        setSaved(EMAIL.test(email))
      }}
    >
      <Input label="Full name" defaultValue="Nora Lindgren" autoComplete="name" />
      <Input
        label="Email"
        type="email"
        value={email}
        autoComplete="email"
        helper="We send receipts to this address."
        error={invalid ? "Enter an email address like name@company.com." : undefined}
        onChange={(event) => setEmail(event.target.value)}
        onBlur={() => setTouched(true)}
      />
      <Input label="Company" optional defaultValue="WunderUI" autoComplete="organization" />
      <Textarea label="Short bio" optional value={bio} maxLength={160} showCount onChange={(event) => setBio(event.target.value)} />
      <div className="flex items-center justify-end gap-2">
        <p aria-live="polite" className="mr-auto text-sm text-text-secondary">
          {saved ? "Profile saved." : ""}
        </p>
        <Button type="submit" variant="gradient">
          Save profile
        </Button>
      </div>
    </form>
  )
}
```

### Payment: fields that format as you type

The card number is grouped in fours and the expiry date gets its slash while typing. Every field keeps its own label, and the number keys come up on a phone.

```tsx
import { useState } from "react"
import { CreditCard } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"

/** Groups the digits of a card number in fours. */
const formatCard = (value: string) =>
  value
    .replace(/\D/g, "")
    .slice(0, 16)
    .replace(/(\d{4})(?=\d)/g, "$1 ")

/** Adds the slash of an expiry date after the month. */
const formatExpiry = (value: string) => {
  const digits = value.replace(/\D/g, "").slice(0, 4)
  return digits.length > 2 ? `${digits.slice(0, 2)} / ${digits.slice(2)}` : digits
}

export function Example() {
  const [card, setCard] = useState("")
  const [expiry, setExpiry] = useState("")

  return (
    <form className="flex flex-col gap-4" onSubmit={(event) => event.preventDefault()}>
      <Input label="Name on card" placeholder="Nora Lindgren" autoComplete="cc-name" />
      <Input
        label="Card number"
        leading={<CreditCard aria-hidden />}
        inputMode="numeric"
        autoComplete="cc-number"
        placeholder="1234 1234 1234 1234"
        value={card}
        onChange={(event) => setCard(formatCard(event.target.value))}
      />
      <div className="grid grid-cols-2 gap-4">
        <Input
          label="Expiry date"
          inputMode="numeric"
          autoComplete="cc-exp"
          placeholder="MM / YY"
          value={expiry}
          onChange={(event) => setExpiry(formatExpiry(event.target.value))}
        />
        <Input label="Security code" inputMode="numeric" autoComplete="cc-csc" maxLength={4} placeholder="123" />
      </div>
      <Button type="submit" variant="gradient">
        Pay $69.98
      </Button>
    </form>
  )
}
```

### Coupon: a field with an action beside it

Apply is explicit: the button shows a spinner while it runs, then a message with an icon appears below the field. Try WUNDER20, then any other code.

```tsx
import { useState } from "react"
import { Check, CircleAlert } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Field } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function Example() {
  const [code, setCode] = useState("")
  const [result, setResult] = useState<"idle" | "pending" | "applied" | "invalid">("idle")

  const apply = () => {
    setResult("pending")
    window.setTimeout(() => setResult(code.trim().toUpperCase() === "WUNDER20" ? "applied" : "invalid"), 700)
  }

  return (
    <Field invalid={result === "invalid"}>
      <Label htmlFor="coupon" className="mb-1">
        Coupon code
      </Label>
      <div className="flex gap-2">
        <Input
          id="coupon"
          placeholder="WUNDER20"
          value={code}
          aria-invalid={result === "invalid"}
          onChange={(event) => {
            setCode(event.target.value)
            setResult("idle")
          }}
        />
        <Button variant="plain" pending={result === "pending"} disabled={code.trim() === ""} onClick={apply} className="shrink-0">
          Apply
        </Button>
      </div>
      <p aria-live="polite" className="min-h-5 text-xs">
        {result === "applied" && (
          <span className="flex items-center gap-1 text-text-success">
            <Check className="size-3.5" aria-hidden /> Coupon applied: 20% off your order.
          </span>
        )}
        {result === "invalid" && (
          <span className="flex items-center gap-1 text-text-error">
            <CircleAlert className="size-3.5" aria-hidden /> This code is not valid. Enter another code.
          </span>
        )}
      </p>
    </Field>
  )
}
```

## For AI agents

`get_component("input")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
