Input
FreeTake one line of text, such as a name, an email address or a search term.
npx wunderui-cli add inputPlayground
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
Installation
npx wunderui-cli add inputWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Input } from "@/components/ui/input"
import type { InputFieldProps, InputProps } from "@/components/ui/input"Then use it:
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.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
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.
- TaborShift+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 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.
- 1
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.
- 2data-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.
- 3data-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.
- 4data-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.
| Prop | Type | Default | Description |
|---|---|---|---|
| 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 . |
| label | ReactNode | — | 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. |
| helper | ReactNode | — | A hint under the field in 12 px tertiary text, linked with . Replaced by while there is one. |
| error | ReactNode | — | The message under the field in the error colour. Sets , turns the border and the ring red and replaces . |
| leading | ReactNode | — | An icon or a short text inside the field before the value. The Input is drawn in an . |
| trailing | ReactNode | — | An icon, a unit or a button inside the field after the value. With , it sits before the reveal button. |
| revealable | boolean | — | With , adds a button that shows or hides what was typed. It has and the label or . Default . |
| labelTrailing | ReactNode | — | A note or a link on the label row, right-aligned, such as or . |
| optional | boolean | — | Adds the tag after the label. It is part of the accessible name. |
| wrapperClassName | string | — | Class names for the column around label row, field and message. still goes to the . |
| Prop | Type | Default | Description |
|---|---|---|---|
| error | ReactNode | — | Error message below the field. Sets and . |
| helper | ReactNode | — | Hint below the field. Replaced by while there is one. |
| label | ReactNode | — | Visible label. Joined to the control with . |
| labelTrailing | ReactNode | — | A tag or a link on the label row, right-aligned (for example "Forgot password?"). |
| leading | ReactNode | — | Content inside the field, before the text (icon, prefix). |
| optional | boolean | — | Adds the "(optional)" tag to the label. |
| revealable | boolean | — | With : adds the button that shows or hides what was typed. |
| size | "default" | "lg" | "sm" | — | |
| trailing | ReactNode | — | Content inside the field, after the text (icon, suffix, button). |
| wrapperClassName | string | — | Class names for the wrapper around label, field and message. |
| Prop | Type | Default | Description |
|---|---|---|---|
| error | ReactNode | — | Error message below the field. Sets and . |
| helper | ReactNode | — | Hint below the field. Replaced by while there is one. |
| label | ReactNode | — | Visible label. Joined to the control with . |
| labelTrailing | ReactNode | — | A tag or a link on the label row, right-aligned (for example "Forgot password?"). |
| leading | ReactNode | — | Content inside the field, before the text (icon, prefix). |
| optional | boolean | — | Adds the "(optional)" tag to the label. |
| revealable | boolean | — | With : adds the button that shows or hides what was typed. |
| size | "default" | "lg" | "sm" | — | |
| trailing | ReactNode | — | Content inside the field, after the text (icon, suffix, button). |
| wrapperClassName | string | — | Class names for the wrapper around label, field and message. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("input")npx wunderui-cli add inputThe full library index for assistants is at /llms.txt.