Skip to content
flyingsalmon

Input

A single-line text field that owns its label, its error message, and its busyness.

Installation

npx shadcn@latest add @flyingsalmon/input

Usage

import { useState } from 'react'

import { Input } from '@/components/ui/input'

export function InputUsage() {
  const [tripName, setTripName] = useState('')

  return (
    <Input
      label="Trip name"
      value={tripName}
      onChange={(event) => setTripName(event.target.value)}
    />
  )
}

Examples

Types

Pick the type that matches the text. It chooses the mobile keyboard and the browser's autofill. Password hides the characters.

Sizes

Default and small match the two button heights, so a field and its submit button line up in a row.

End adornment: icon

A plain icon describes the field. Mark it aria-hidden, because the label already says what the field is.

End adornment: action

A ghost field-icon button acts on the field. Tab reaches the field first and the button second.

Description

Helper text sits under the field and joins its accessible description.

We send the itinerary here

Error

The description stays where it is and the message grows in below it.

We send the itinerary here

Enter a valid email address

Loading

Tab out of the field after typing. The spinner shows while the check runs, the field stays editable, and the answer lands in the field's own error.

Type linh@example.com, then tab out to check

Disabled

The field and its label dim together and take no pointer events.

Read-only

The value stays readable and copyable on a muted background, and the field stays focusable.

Guidelines

When to use

  • For one line of free text: a trip name, an email address, a phone number, a booking link.
  • For a value the traveller types rather than picks, where any text is acceptable input.

When not to use

  • Use Number field when the value is a quantity. It formats for the page’s locale, clamps to its bounds, and reports a number instead of a string.
  • Use Textarea for notes that run past one line, because it grows with what the traveller types.
  • Use Combobox when the traveller picks a place, a person, or any value from a list you control.
  • Use Date picker for a calendar day or a range of days, so the segments and the grid refuse impossible dates.

Do and don’t

  • Do
    Give every input a visible label above it, and use the placeholder for an example answer such as linh@example.com.The label asks the question and stays put. A placeholder disappears as soon as the traveller types, so it only ever shows the shape of a good answer.
  • Do
    Show a failed check on the field that caused it, and clear it the moment the traveller edits.The border, the label, and the message sit next to the text that caused the failure. Clearing on the first keystroke shows the field is listening, not scolding.
  • Don’t
    Lock the field while it checks a value.A spinner in the end slot shows the check and the field stays editable, so a typo can be fixed while it runs. Only the submit button locks a flow.
  • Do
    Put the copy action for a read-only value inside the field, as a ghost icon button, and confirm the copy by turning its icon to a check.The action sits next to the value it acts on, and the confirmation appears on the button the traveller just pressed.
  • Don’t
    Stretch a field across the whole column when its answer is short.The width tells the traveller how long an answer you expect. A postcode in a full-width field looks like it wants a paragraph.

Accessibility

KeyDescription
TabMoves focus into the field, then to an interactive end adornment.
Shift+TabMoves focus back the same way.
EnterSubmits the enclosing form through native implicit submission.

Input generates the field id and wires the label to it, so clicking the label focuses the field. An error sets aria-invalid, and aria-describedby lists any ids you passed, then the error message, then the description. A loading field sets aria-busy and hides its spinner from screen readers, so the wait is announced once. required marks the label and reaches the <input>; the validation itself stays with your app. The states every field shares are described on Fields.

API

Input

Also takes every <input> attribute except size and type, which it redefines. className styles the wrapper that holds the label, the field, and the message, so a width set there sizes the whole field.

PropTypeDefaultDescription
labelstring–The visible label. Renders above the field and is wired to it.
typeInputTypeInputType.TextText, Email, Password, Number, Search, Telephone, or Url. A quantity takes Number field instead, which reports a number and enforces its bounds.
sizeInputSizeInputSize.DefaultDefault and Small match the field heights of the same names.
descriptionstring–Helper text under the field.
errorstring–The failure message. Turns the border, the ring, and the label destructive.
loadingbooleanfalseShows a spinner in the end slot, replacing endAdornment. The field stays editable. Set it, not disabled, while a check runs.
endAdornmentReactNode–An icon or a ghost field-icon button inside the border, on the right.
disabledbooleanfalseDims the field and its label and removes both from the tab order.
readOnlybooleanfalseKeeps the value readable on a muted background. The field stays focusable.
requiredbooleanfalseMarks the label and sets the native attribute.

  • Fields

    The label, description, error, loading, and disabled behaviour every field shares.
  • Textarea

    The multiline counterpart for longer notes.
  • Number field

    The field for quantities, with steps and bounds.
  • Form

    Lays fields out with an actions row and a result slot.