Input

A cross-platform text input with label, error, icon, clear and validation support; works on web and React Native via XUIProvider themed contexts.

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.

Installation

npm install @xsolla/xui-input

Imports

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

Quick start

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

<Input
  label="Email"
  value={value}
  onChangeText={setValue}
  placeholder="[email protected]"
/>;

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

<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

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

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

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

Validation

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

<Input
  label="Email"
  value={email}
  onChangeText={setEmail}
  error={!!error}
  errorMessage={error}
  placeholder="[email protected]"
/>;

Disabled and success

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

Custom border radius

<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.