> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Input

Data Entry`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Single-line text input for short freeform values.

## When to use

Use Input for short text values such as names, filters, search terms, and identifiers.

**Recommended**

- Pair with FormField for labels and validation.
- Use type, inputMode, and autoComplete when applicable.

**Avoid**

- Do not use the component outside its intended interaction model.

## Examples


### Basic usage
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';

function InputExample() {
  return (
    <Stack gap="md" style={{ maxWidth: 400 }}>
      <Input placeholder="Default input" />
      <Input prefix={<span aria-hidden="true">⌕</span>} placeholder="Search" />
      <Input value="Invalid value" error readOnly />
      <Input placeholder="Disabled" disabled />
    </Stack>
  );
}

export default InputExample;
```

### Variants
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';

function InputVariants() {
  return (
    <Stack gap="md" style={{ maxWidth: 400 }}>
      <Input variant="outlined" placeholder="Outlined" />
      <Input variant="filled" placeholder="Filled" />
      <Input variant="borderless" placeholder="Borderless" />
      <Input variant="underlined" placeholder="Underlined" />
    </Stack>
  );
}

export default InputVariants;
```

### Sizes and affixes
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';

function InputSizes() {
  return (
    <Stack gap="md" style={{ maxWidth: 400 }}>
      <Input
        size="small"
        prefix={<span aria-hidden="true">⌕</span>}
        placeholder="Small search"
      />
      <Input
        size="medium"
        suffix={<span>USD</span>}
        placeholder="Medium amount"
      />
      <Input size="large" placeholder="Large input" />
    </Stack>
  );
}

export default InputSizes;
```

### Three sizes
Choose a size for regular forms, compact toolbars, or spacious layouts.
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      {(['small', 'medium', 'large'] as const).map((size) => (
        <Input key={size} size={size} aria-label={size} placeholder={size} />
      ))}
    </Stack>
  );
}
```

### Clear and count
Clearing calls onChange and onClear. Controlled values remain owned by your state.
```tsx preview
import { useState } from 'react';
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [value, setValue] = useState('tao-ui');
  return <Stack direction="vertical">
    <Input aria-label="Project name" value={value} onChange={(e) => setValue(e.target.value)} allowClear showCount maxLength={24} />
    <Input aria-label="Read-only name" value="Read-only" readOnly allowClear />
    <output>{value || 'Empty'}</output>
  </Stack>;
}
```

### Prefixes and suffixes
Affixes show units or context while the input value contains only user data.
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      <Input
        aria-label="Website"
        prefix="https://"
        suffix=".com"
        placeholder="example"
      />
      <Input
        aria-label="Budget"
        prefix="$"
        suffix="USD"
        type="number"
        defaultValue="1200"
      />
    </Stack>
  );
}
```

### Password input
The visibility button supports keyboard access, disabled state, and controlled visibilityToggle.
```tsx preview
import { useState } from 'react';
import { Input, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [visible, setVisible] = useState(false);
  return <Stack direction="vertical">
    <Input.Password aria-label="Password" defaultValue="example-password" autoComplete="new-password" allowClear />
    <Input.Password aria-label="Controlled password" defaultValue="controlled" visibilityToggle={{ visible, onVisibleChange: setVisible }} />
    <Button onClick={() => setVisible(!visible)}>{visible ? 'Hide' : 'Show'}</Button>
  </Stack>;
}
```

### Search input
Button clicks, Enter and clearing call onSearch with source input or clear. IME confirmation and loading do not submit a search.
```tsx preview
import { useState } from 'react';
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [result, setResult] = useState('No search yet');
  return <Stack direction="vertical">
    <Input.Search aria-label="Search components" placeholder="Search components" allowClear enterButton="Search" onSearch={(value, _, info) => setResult(`${info?.source}: ${value || '(empty)'}`)} />
    <Input.Search aria-label="Loading search" value="Loading" loading readOnly />
    <output aria-live="polite">{result}</output>
  </Stack>;
}
```

### Native constraints and read-only
Use native email, required, maxLength, and readOnly; application state decides error feedback.
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      <Input
        aria-label="Email"
        type="email"
        required
        placeholder="name@example.com"
      />
      <Input
        aria-label="Short code"
        maxLength={6}
        placeholder="Up to 6 characters"
      />
      <Input aria-label="Record ID" readOnly value="REC-1042" />
      <Input
        aria-label="Invalid value"
        status="error"
        defaultValue="Invalid value"
      />
    </Stack>
  );
}
```

### Cursor placement
The ref remains the native input. InputRef also exposes input, nativeElement and extended focus options.
```tsx preview
import { useRef } from 'react';
import { Input, type InputRef, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const ref = useRef<InputRef>(null);
  return <Stack direction="vertical">
    <Input ref={ref} aria-label="Focus target" defaultValue="Select this text" />
    <Stack wrap>
      {(['start', 'end', 'all'] as const).map((cursor) => <Button key={cursor} onClick={() => ref.current?.focus({ cursor, preventScroll: true })}>{cursor}</Button>)}
    </Stack>
  </Stack>;
}
```

### Custom counting
count.max warns by default. strategy and exceedFormatter can count and clip Unicode code points. Native maxLength counts UTF-16 code units independently.
```tsx preview
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return <Stack direction="vertical">
    <Input aria-label="Soft limit" defaultValue="More than five" count={{ max: 5, show: true }} />
    <Input aria-label="Emoji counter" defaultValue="😊😊" count={{ max: 5, show: true, strategy: (value) => Array.from(value).length, exceedFormatter: (value, { max }) => Array.from(value).slice(0, max).join('') }} />
  </Stack>;
}
```

### Text area
Input.TextArea is the same component as standalone Textarea, with auto sizing, clearing, counting and Enter events.
```tsx preview
import { Input } from '@rockshin/tao-ui';
export default function Example() {
  return <Input.TextArea aria-label="Description" placeholder="Write a description" autoSize={{ minRows: 2, maxRows: 5 }} allowClear showCount maxLength={120} />;
}
```

### One-time code
Supports automatic advance, pasting, arrow keys, Backspace, formatting and masking. onInput returns an array including empty slots; onChange fires only when complete.
```tsx preview
import { useState } from 'react';
import { Input, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [complete, setComplete] = useState('');
  return <Stack direction="vertical">
    <Input.OTP aria-label="Verification code" length={6} autoComplete="one-time-code" formatter={(value) => value.toUpperCase()} separator={(index) => index === 2 ? '-' : null} onChange={setComplete} />
    <Input.OTP aria-label="Masked code" length={4} mask defaultValue="1234" />
    <output aria-live="polite">{complete || 'Enter all characters'}</output>
  </Stack>;
}
```

### Attached content
addonBefore / addonAfter attach labels; prefix / suffix sit inside the input area.
```tsx preview
import { Input } from '@rockshin/tao-ui';
export default function Example() {
  return <Input aria-label="Website address" addonBefore="https://" addonAfter=".com" defaultValue="example" allowClear />;
}
```

## API

### Input / Input.TextArea

Other props pass through to the native input / textarea. Input.TextArea does not accept prefix, suffix or addons; standalone Textarea remains compatible.

| Prop                     | Type                                                                                                                | Default               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------- | --------------------- |
| value / defaultValue     | Native input value / textarea value                                                                                 | —                     |
| onChange                 | `(event) => void`                                                                                                   | —                     |
| allowClear               | `boolean` or `{ clearIcon?, disabled?, tabIndex? }`                                                                 | `false`               |
| onClear                  | `() => void`                                                                                                        | —                     |
| showCount                | `boolean` or `{ formatter: ({ value, count, maxLength }) => ReactNode }`                                            | `false`               |
| count                    | `{ max?, strategy?: (value) => number, show?: boolean or formatter, exceedFormatter?: (value, { max }) => string }` | —                     |
| onPressEnter             | `(event: KeyboardEvent) => void`                                                                                    | —                     |
| size                     | `'small'`, `'medium'`, `'large'`                                                                                    | TaoProvider           |
| variant                  | `'outlined'`, `'filled'`, `'borderless'`, `'underlined'`                                                            | TaoProvider           |
| status / error           | `'error'` or `'warning'` / `boolean`                                                                                | —                     |
| disabled / readOnly      | `boolean`                                                                                                           | TaoProvider / `false` |
| prefix / suffix          | `ReactNode` (Input only)                                                                                            | —                     |
| addonBefore / addonAfter | `ReactNode` (Input only)                                                                                            | —                     |
| autoSize                 | `boolean` or `{ minRows?, maxRows? }` (TextArea only)                                                               | `false`               |
| classNames / styles      | Semantic part map or `({ props }) => map`                                                                           | —                     |

A count limit does not clip unless count.exceedFormatter is set. Clipping waits for IME composition to finish. count.show takes precedence over showCount. Input semantic parts: root / input / prefix / suffix / clear / count / addonBefore / addonAfter. TextArea: root / textarea / clear / count.

### Input.Password

Inherits Input props.

| Prop             | Type                                                     | Default  |
| ---------------- | -------------------------------------------------------- | -------- |
| visibilityToggle | `boolean` or `{ visible?, onVisibleChange?, tabIndex? }` | `true`   |
| iconRender       | `(visible: boolean) => ReactNode`                        | Eye icon |

### Input.Search

Inherits Input props. The search button does not submit a surrounding form; onSearch reports source input or clear.

| Prop                | Type                                                             | Default     |
| ------------------- | ---------------------------------------------------------------- | ----------- |
| enterButton         | `ReactNode` (boolean, label, native button or Button)            | `false`     |
| searchIcon          | `ReactNode`                                                      | Search icon |
| loading             | `boolean`                                                        | `false`     |
| onSearch            | `(value, event?, info?: { source: 'input' or 'clear' }) => void` | —           |
| classNames / styles | Input parts plus `button`                                        | —           |

### Input.OTP

| Prop                            | Type                                                   | Default                       |
| ------------------------------- | ------------------------------------------------------ | ----------------------------- |
| length                          | Positive integer                                       | `6`                           |
| value / defaultValue            | `string`                                               | —                             |
| formatter                       | `(value: string) => string`                            | —                             |
| onInput                         | `(value: string[]) => void`                            | —                             |
| onChange                        | `(value: string) => void` (complete values)            | —                             |
| mask                            | `boolean` or `string`                                  | `false`                       |
| separator                       | `ReactNode` or `(index: number) => ReactNode`          | —                             |
| type / inputMode / autoComplete | Native input attributes                                | `text` / — / —                |
| autoFocus / disabled            | `boolean`                                              | `false` / TaoProvider         |
| size / variant / status         | Same as Input                                          | TaoProvider / TaoProvider / — |
| classNames / styles             | `root / input / separator` map or `({ props }) => map` | —                             |

### Ref

Input, Password and Search refs remain HTMLInputElement; TextArea remains HTMLTextAreaElement. Exported InputRef / TextAreaRef types add `focus({ preventScroll, cursor: 'start' | 'end' | 'all' })`, blur(), nativeElement and input / textArea. Native types without selection support only receive focus. OTPRef exposes focus(), blur() and nativeElement.

The API follows local Ant Design 6.7.0 while retaining tao-ui native refs, theming and semantic DOM contracts; it is not a drop-in antd replacement. Deprecated bordered, prefixCls and antd component-global configuration are not supported. Set underlined through the local Input-family variant prop.
