# Input

A single-line text input.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="input" />

<ComponentPreview name="input" title="input.tsx" previewClassName="h-auto py-8">
<InputDemo />
</ComponentPreview>

Input is a single-line text field for forms and inline editing. It inherits all native `<input>` attributes and behaviors, and pairs with [Field](/docs/components/field) for labels and descriptions.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add input
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="input" title="components/ui/input.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="input.tsx"
import { Input } from "@/components/ui/input";
```

```tsx
<Input placeholder="Email" type="email" />
```

## Examples [#examples]

### Basic [#basic]

<ComponentPreview name="input-basic" src="examples/input-basic.tsx" title="input-basic.tsx" previewClassName="h-auto py-8">
<InputBasic />
</ComponentPreview>

```tsx
<Input placeholder="Enter text" />
```

### With label [#with-label]

<ComponentPreview name="input-field" src="examples/input-field.tsx" title="input-field.tsx" previewClassName="h-auto py-8">
<InputField />
</ComponentPreview>

```tsx
<Field>
  <FieldLabel htmlFor="username">Username</FieldLabel>
  <Input id="username" placeholder="Enter your username" />
  <FieldDescription>
    Choose a unique username for your account.
  </FieldDescription>
</Field>
```

### Form [#form]

Use [FieldGroup](/docs/components/field) for multiple fields with consistent spacing.

<ComponentPreview name="input-fieldgroup" src="examples/input-fieldgroup.tsx" title="input-fieldgroup.tsx" previewClassName="h-auto py-8">
<InputFieldgroup />
</ComponentPreview>

```tsx
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="name">Name</FieldLabel>
    <Input id="name" placeholder="Jordan Lee" />
  </Field>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" type="email" placeholder="name@example.com" />
  </Field>
  <Field orientation="horizontal">
    <Button type="submit">Submit</Button>
  </Field>
</FieldGroup>
```

### Invalid [#invalid]

Set `aria-invalid` on the input, or `data-invalid` on the **Field** wrapper, to trigger destructive styling.

<ComponentPreview name="input-invalid" src="examples/input-invalid.tsx" title="input-invalid.tsx" previewClassName="h-auto py-8">
<InputInvalid />
</ComponentPreview>

```tsx
<Field data-invalid>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input id="email" aria-invalid />
  <FieldDescription>This field contains validation errors.</FieldDescription>
</Field>
```

### Types [#types]

```tsx
<Input type="email" placeholder="Email" />
<Input type="password" placeholder="Password" />
<Input type="search" placeholder="Search" />
<Input type="file" />
```

## In Context [#in-context]

### Email field [#email-field]

<ComponentPreview name="input-email" src="examples/input-email.tsx" title="input-email.tsx">
<r />
</ComponentPreview>

### Search bar [#search-bar]

For an icon inside the input surface, use [Input Group](/docs/components/input-group):

<ComponentPreview name="input-group-demo" src="examples/input-group-demo.tsx" title="input-group-demo.tsx">
<InputGroupDemo />
</ComponentPreview>

## States [#states]

| State | How |
| :-- | :-- |
| Default | — |
| Focus | keyboard focus on the field |
| Invalid | `aria-invalid="true"` |
| Disabled | `disabled` prop |

```tsx
<Input aria-invalid="true" placeholder="Email" />
<Input disabled placeholder="Disabled" />
```

## API Reference [#api-reference]

### Input [#input]

Extends `React.ComponentProps<"input">`.

<PropsTable rows={[{"name":"type","type":"string","default":"\"text\"","description":"Native input type."},{"name":"placeholder","type":"string","description":"Shown when the input is empty."},{"name":"value","type":"string","description":"Controlled value."},{"name":"defaultValue","type":"string","description":"Uncontrolled initial value."},{"name":"onChange","type":"React.ChangeEventHandler<HTMLInputElement>","description":"Fires on every keystroke."},{"name":"disabled","type":"boolean","default":"false","description":"Removes the input from the tab order."},{"name":"aria-invalid","type":"boolean","description":"Marks the input as invalid; pair with aria-describedby."}]} />

## Accessibility [#accessibility]

- `Input` renders a native `<input>`. It has no label by default; always pair with a `Label` or `FieldLabel`.
- Use the native `type` attribute (`email`, `url`, `tel`, `number`) so mobile keyboards adapt.
- Set `aria-invalid` and `aria-describedby` on error. Do not rely on a red border alone.
- `disabled` removes the input from the tab order. For informational values, use `readOnly`.

## Best Practices [#best-practices]

- **Always label the input.** Placeholders disappear after typing; labels stay.
- **Use the native type.** `email`, `url`, `tel`, and `number` trigger the right keyboard on mobile.
- **Show errors inline.** Use `aria-invalid` and a description below the input, not a toast.
- **Do not disable without reason.** Disabled inputs are invisible to screen readers.
- **Cap length with `maxLength`.** Do not rely on server-side validation alone.

## Anatomy [#anatomy]

<ComponentPreview name="input-anatomy" src="examples/input-anatomy.tsx" title="input-anatomy.tsx">
<l />
</ComponentPreview>

- **Field** — 36px height, 1px border, 6px radius
- **Text** — 14px, inherits `foreground`
- **Placeholder** — `muted-foreground`, disappears on input
- **Focus ring** — `ring-3` in `ring` color on focus

## Related Components [#related-components]

- [Field](/docs/components/field) — label, description, and error wrapper
- [Input Group](/docs/components/input-group) — add icons and buttons
- [Input OTP](/docs/components/input-otp) — one-time password input
- [Textarea](/docs/components/textarea) — multi-line variant