Skip to content
WunderUI

Input

Free

Take one line of text, such as a name, an email address or a search term.

npx wunderui-cli add input

Playground

We send receipts to this address.

Installation

bash
npx wunderui-cli add input

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import { Input } from "@/components/ui/input"
import type { InputFieldProps, InputProps } from "@/components/ui/input"

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.

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 for

  • Textarea for text over several lines, such as a message or feedback
  • Number Field for a quantity with plus and minus buttons
  • Select for a choice from a short list of known options
  • OTP Field for a one-time code typed in separate cells

Types

The type sets the keyboard on a phone, what the browser offers to fill in and how the value is checked. A password field can add a button that shows what was typed.

Sizes

Three heights that match the three smaller Button sizes, so a field and a button of the same size line up. Comfortable density adds 4 px to each.

Label, helper and error

Every field has a visible label joined to the input. The helper gives the rule before the person breaks it, the error replaces it with what to do, and a note or link can sit on the label row.

Leading and trailing content

Leading and trailing content puts an icon or text inside the field, and an Input Group draws the border and focus ring around it. A button inside keeps 2 px of air and a 6 px corner.

States

Hover and focus are real states: move the pointer over a field, or press Tab. A wrong value turns the border and ring red, and the fill stays white.

We send receipts to this address.

Keyboard interactions

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

TaborShiftTab
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 the browser clears what was typed. In other types it does nothing.
TaborSpaceorEnter
With , 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 and motion

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

Input is the field itself. Label, helper text and inside content are parts you put around it; an Input Group draws the border when there is content inside.

  • 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.

  • data-slot="input-field"

    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.

  • data-slot="input-group-addon"Optional

    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.

  • data-slot="icon-button"Optional

    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.

  • Optional

    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.

  • Optional

    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.

  • data-slot="input"
  • Optional
  • Optional

Best practices

  • 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.

  • Do

    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.

  • Do

    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.

  • Do

    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.

  • Do

    Keep the label a noun (Work email) and put the rule in the helper below it as a full sentence.

  • Do

    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

    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

    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

    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

    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 renders a native input and takes all its attributes plus a ref. The table lists the props the library adds: size and the field props; Input Group, Field and Label have their own pages.

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.

PropTypeDefaultDescription
size"default" | "lg" | "sm"—The height of the field. is 32 px, 36 px and 40 px at the default density, and 36, 44 and 52 px in . The same heights as the Button sizes , and .
labelReactNode—The visible name of the field. Joined to the input with . Any field prop makes the Input render the label row, the field and the message line instead of the bare input.
helperReactNode—A hint under the field in 12 px tertiary text, linked with . Replaced by while there is one.
errorReactNode—The message under the field in the error colour. Sets , turns the border and the ring red and replaces .
leadingReactNode—An icon or a short text inside the field before the value. The Input is drawn in an .
trailingReactNode—An icon, a unit or a button inside the field after the value. With , it sits before the reveal button.
revealableboolean—With , adds a button that shows or hides what was typed. It has and the label or . Default .
labelTrailingReactNode—A note or a link on the label row, right-aligned, such as or .
optionalboolean—Adds the tag after the label. It is part of the accessible name.
wrapperClassNamestring—Class names for the column around label row, field and message. still goes to the .

PropTypeDefaultDescription
errorReactNode—Error message below the field. Sets and .
helperReactNode—Hint below the field. Replaced by while there is one.
labelReactNode—Visible label. Joined to the control with .
labelTrailingReactNode—A tag or a link on the label row, right-aligned (for example "Forgot password?").
leadingReactNode—Content inside the field, before the text (icon, prefix).
optionalboolean—Adds the "(optional)" tag to the label.
revealableboolean—With : adds the button that shows or hides what was typed.
size"default" | "lg" | "sm"—
trailingReactNode—Content inside the field, after the text (icon, suffix, button).
wrapperClassNamestring—Class names for the wrapper around label, field and message.

PropTypeDefaultDescription
errorReactNode—Error message below the field. Sets and .
helperReactNode—Hint below the field. Replaced by while there is one.
labelReactNode—Visible label. Joined to the control with .
labelTrailingReactNode—A tag or a link on the label row, right-aligned (for example "Forgot password?").
leadingReactNode—Content inside the field, before the text (icon, prefix).
optionalboolean—Adds the "(optional)" tag to the label.
revealableboolean—With : adds the button that shows or hides what was typed.
size"default" | "lg" | "sm"—
trailingReactNode—Content inside the field, after the text (icon, suffix, button).
wrapperClassNamestring—Class names for the wrapper around label, field and message.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("input")
Installnpx wunderui-cli add input

The full library index for assistants is at /llms.txt.