# Input

A cross-platform text input with label, error, icon, clear and validation support; works on web and React Native via `XUIProvider` themed contexts.
<!-- BEGIN:xui-mcp-instructions:input -->
An interactive field that lets users enter, edit, or review information. Inputs communicate what kind of data is expected and help users provide the information needed to complete tasks, make updates, or refine content across the product.

### When to use
- When you need to collect a short, freeform text value from a user (name, email, search query, etc.)
- When the expected input fits on a single line
- As part of a larger form alongside other controls

### When not to use
- When the expected input spans multiple lines — use a TextArea instead
- When the user must pick from a predefined list — use a Select, MultiSelect or Autocomplete instead
- When the value is numeric with constraints — use a InputPhone or InputRange instead
- When the value is card number — use a InputPayment instead
- When the value is time or date — use a InputTime or DatePicker instead
- When the value is pin code — use a InputPin instead

### Content guidelines
- Do not use the placeholder as a substitute for a label.
- Placeholder text should describe the expected format or example value (e.g. *"Enter your email"*, *"DD/MM/YYYY"*), not repeat the label.
- Error messages should be constructive: explain what is wrong and how to correct it (e.g. *"Email is required"*, not just *"Invalid input"*).
- Remove button should appear only when the field has a value, giving users a quick way to clear it.
- Check icon should appear after successful validation to confirm the value is accepted.

### Behavior guidelines
- Input width — fields should reflect the expected content length; avoid overly wide fields for short values like ZIP code, OTP, or CVV unless the layout requires it.
- Validation timing — do not show errors before a user has interacted with the field. Validate on blur, on submit, or progressively while typing only when it meaningfully helps.
- Error state — preserve the user’s entered value, show error text close to the field, and do not rely on color alone to communicate the problem.

### Accessibility
- Error messages must be linked to the input via `aria-describedby` so screen readers announce them on focus.
- Never rely on placeholder text alone to communicate the field's purpose — it disappears on input and has low contrast by default.
- Disabled fields should not receive keyboard focus; consider using a read-only state if the value still needs to be accessible.
<!-- END:xui-mcp-instructions:input -->

## Installation

```bash
npm install @xsolla/xui-input
```

## Imports

```tsx
import { Input } from '@xsolla/xui-input';
import type { InputProps } from '@xsolla/xui-input';
```

## Quick start

```tsx
const [value, setValue] = useState('');

<Input
  label="Email"
  value={value}
  onChangeText={setValue}
  placeholder="you@example.com"
/>;
```

## API Reference

### `<Input>`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Controlled value. |
| `placeholder` | `string` | — | Placeholder shown when empty. |
| `onChange` | `(e: ChangeEvent<HTMLInputElement>) => void` | — | Native change handler. |
| `onChangeText` | `(text: string) => void` | — | Simplified change handler receiving the text. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Control size. |
| `disabled` | `boolean` | `false` | Disable the input. |
| `label` | `string` | — | Label rendered above the input. |
| `error` | `boolean` | `false` | Apply error styling. |
| `errorMessage` | `string` | — | Error message; also marks the input invalid. |
| `iconLeft` | `ReactNode` | — | Icon on the left. |
| `iconRight` | `ReactNode` | — | Icon on the right. |
| `iconRightSize` | `number \| string` | — | Override the right-icon size. |
| `extraClear` | `boolean` | `false` | Show a clear button when the input has a value. |
| `onRemove` | `() => void` | — | Fired when the clear button is pressed. |
| `checked` | `boolean` | `false` | Show a success indicator (suppressed when `errorMessage` is set). |
| `checkedIcon` | `ReactNode` | `<CheckCr />` | Override the checked icon. |
| `borderTopLeftRadius` | `number` | — | Override top-left corner radius. |
| `borderTopRightRadius` | `number` | — | Override top-right corner radius. |
| `borderBottomLeftRadius` | `number` | — | Override bottom-left corner radius. |
| `borderBottomRightRadius` | `number` | — | Override bottom-right corner radius. |
| `backgroundColor` | `string` | — | Override the background colour. |
| `id` | `string` | `auto` | HTML id; also wires up the label. |
| `aria-label` | `string` | — | Accessible label when no visible label is present. |
| `testID` | `string` | — | Test identifier. |

`Input` also accepts the standard `InputHTMLAttributes` (excluding `size` and `onChange`, which are redefined above).

Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).

## Examples

### Sizes

```tsx
<Input size="xs" placeholder="Extra small" />
<Input size="sm" placeholder="Small" />
<Input size="md" placeholder="Medium" />
<Input size="lg" placeholder="Large" />
<Input size="xl" placeholder="Extra large" />
```

### Icons

```tsx
import { Search, Check } from '@xsolla/xui-icons';
import { Mail } from '@xsolla/xui-icons-base';

<Input iconLeft={<Search />} placeholder="Search..." />
<Input iconLeft={<Mail />} iconRight={<Check />} placeholder="Email" />
```

### Clear button

```tsx
const [value, setValue] = useState('Some text');

<Input
  value={value}
  onChangeText={setValue}
  extraClear
  onRemove={() => setValue('')}
  placeholder="Type something..."
/>;
```

### Validation

```tsx
const [email, setEmail] = useState('');
const error = email && !email.includes('@') ? 'Invalid email' : '';

<Input
  label="Email"
  value={email}
  onChangeText={setEmail}
  error={!!error}
  errorMessage={error}
  placeholder="you@example.com"
/>;
```

### Disabled and success

```tsx
<Input label="Disabled" value="Cannot edit" disabled />
<Input label="Username" value="johndoe" checked />
```

### Custom border radius

```tsx
<Input
  placeholder="Rounded"
  borderTopLeftRadius={20}
  borderTopRightRadius={20}
  borderBottomLeftRadius={20}
  borderBottomRightRadius={20}
/>
```

## Accessibility

- Renders a semantic `<input>` whose `aria-labelledby` points at the `id` of the rendered `<label>` element (rather than the standard `<label htmlFor>` pairing).
- Error messages are linked through `aria-describedby` and announced via `role="alert"`.
- `aria-invalid` and `aria-disabled` reflect error and disabled state.
- Pressing Escape blurs the input.