Input

An input is a native text field for short values like a name, an email address or a search. It works inside a field and a form, and adds a clear button, text around the input, and change reasons.

import { Field, FieldDescription, FieldLabel } from "@ui-sdk/react/field"
import { Input, InputClear, InputGroup } from "@ui-sdk/react/input"
import { XIcon } from "lucide-react"
import { useLog } from "./log"

function Example() {
  const log = useLog()

  return (
    <Field name="website">
      <FieldLabel>Website</FieldLabel>
      <InputGroup>
        <span>https://</span>
        <Input
          placeholder="example.com"
          defaultValue="hollisgrant.com"
          onValueChange={(value, details) =>
            log(`${value ? `“${value}”` : "Empty"} (${details.reason})`)
          }
        />
        <InputClear aria-label="Clear website">
          <XIcon aria-hidden="true" />
        </InputClear>
      </InputGroup>
      <FieldDescription>Shown on your public profile.</FieldDescription>
    </Field>
  )
}

export { Example }

Installation

npm install @ui-sdk/react @ui-sdk/core

Composition

Use the following composition to build an Input or an InputGroup:

Input

InputGroup
├── Input
└── InputClear

Input renders a native <input>. Pass its type, placeholder, autocomplete and other native attributes directly. InputGroup holds text or buttons around it, and InputClear empties it.

Usage

Import the parts and put them together:

import { Input, InputClear, InputGroup } from "@ui-sdk/react/input"

function Example() {
  return (
    <InputGroup>
      <Input type="search" aria-label="Search" />
      <InputClear aria-label="Clear search" />
    </InputGroup>
  )
}

export { Example }

Fields

Wrap the input in a Field to give it a visible label, a description and errors. The field also supplies its name when the input has none.

<Field name="username">
  <FieldLabel>Username</FieldLabel>
  <Input autoComplete="username" />
  <FieldDescription>
    Choose a unique username for your account.
  </FieldDescription>
</Field>

Disabled and Read Only

Set disabled on the input or its field to prevent editing and leave it out of the tab order and the submitted values. A readOnly input can still be focused, selected and submitted.

<Field disabled>
  <FieldLabel>Email</FieldLabel>
  <Input type="email" defaultValue="hollis@example.com" />
</Field>

<Field>
  <FieldLabel>Profile URL</FieldLabel>
  <Input readOnly value="example.com/hollis" />
</Field>

Validation

Use native constraints such as required, type="email" and pattern. The field shows its error after a submit attempt and updates it as the value changes. Set invalid on the field for an error your app decides; the input gets aria-invalid. Field covers the error parts and their matches.

<Field name="email" invalid={emailTaken ? true : undefined}>
  <FieldLabel>Email</FieldLabel>
  <Input type="email" required />
  <FieldError match="valueMissing">Enter your email address.</FieldError>
  <FieldError match>That email is already in use.</FieldError>
</Field>

Input Group

Place text or buttons around an input with InputGroup. Pressing the group's text focuses the input. The text is display content, not part of the submitted value.

<InputGroup>
  <span>https://</span>
  <Input aria-label="Website" placeholder="example" />
  <span>.com</span>
</InputGroup>

Clear Button

InputClear shows while the input has text it can clear. Pressing it empties the value, reports clear-press and returns focus to the input. Controlled state and native input listeners receive the change too.

<InputGroup>
  <Input type="search" aria-label="Search people" />
  <InputClear aria-label="Clear search">
    <XIcon aria-hidden="true" />
  </InputClear>
</InputGroup>

Controlled

Pass value and onValueChange to control the input. Native onChange still works.

const [name, setName] = React.useState("Hollis Grant")

<Input value={name} onValueChange={(value) => setName(value)} />

See State and Events for the shared controlled-state conventions. Input's reasons tell typing, clearing, resetting and controller changes apart.

Filtering What's Typed

Call details.cancel() in the value-change callback to reject a change. The previous text and caret position are restored.

<Input
  inputMode="numeric"
  maxLength={6}
  onValueChange={(value, details) => {
    if (!/^\d*$/.test(value)) details.cancel()
  }}
/>

Controller

Use createInputController() for actions outside the input. Its methods update the input through the same change callbacks as typing.

const [message] = React.useState(createInputController)

<Input controller={message} aria-label="Message" />
<button onClick={() => message.setValue("On my way!")}>Quick Reply</button>
<button onClick={() => message.clear()}>Clear</button>
<button onClick={() => message.focus()}>Focus</button>

Controllers covers creating and sharing a controller.

Passwords and Files

Use Password Input to show and hide a password. A native file input works with type="file"; use File Input for dropping, previews and validation.

Styling

Each part has a data-slot, such as input-group, and shows its state through the attributes listed under Data Attributes. Use data-filled, data-disabled, data-readonly and data-required on the input, and the field's validation and focus attributes inside a field. For a group's focus ring, style :has(input:focus-visible), so a focused button inside it keeps its own ring.

Data Attributes

Input

[data-slot="input"]

InputGroup

[data-slot="input-group"]

InputClear

[data-slot="input-clear"]

API Reference

Props are the same as below, as React props, plus every native input prop.

Input

InputGroup

InputClear

A <button> that empties the input in its group and focuses it. It renders only while there's text to clear.

State

InputGroup and InputClear receive the state of the input inside the group.

Reasons

Controller

Create one with createInputController() and pass it as controller.

Accessibility

Give the input a visible field label or an aria-label, and give the clear button an accessible name. The native input keeps standard text editing, selection, autocomplete and form behavior.