Input

Apollion's base text entry field. Other form inputs (InputCurrency, InputDate, InputMask, TextArea, Checkbox, Radio) are built on top of it, inheriting size tokens, state variants, and the icon slot.

When to use

✅ Use when…	🚫 Avoid when…
To collect free text — names, emails, passwords, searches. Whenever you need a controlled field with visual validation feedback (`variant="error"` or `"success"`). As the base when building a custom input: mirroring the `Input` API is cheaper than reinventing it.	For long, multi-line text. Use `TextArea`. For selecting from a list of options. Use `InputSelect`. For monetary values, dates, or masked numbers. Use the derivatives (`InputCurrency`, `InputDate`, `InputMask`).

Sizes

Input has four size variations: micro, compact, medium (default), and expansive.

<Input size="micro" placeholder="micro" />
<Input size="compact" placeholder="compact" />
<Input size="medium" placeholder="medium" />
<Input size="expansive" placeholder="expansive" />

Icons

Icons can be positioned on the left or on the right.

<Input iconPosition="left" icon={<Icon icon={search} />} />
<Input icon={<Icon icon={search} />} />

Variants

Three color variations reflect the validation state: default, error, and success. In error and success, an icon is injected automatically when no icon is provided.

<Input variant="default" />
<Input variant="error" />
<Input variant="success" />

`clearable`

clearable shows an "×" button when there is a value. Outside the Form, you must pass reset to clear the controlled state:

const [value, setValue] = useState('lorem ipsum');
 
<Input clearable value={value} onChange={(e) => setValue(e.target.value)} reset={() => setValue('')} />;

Inside the Form, reset is injected automatically.

Interactive Demo

Properties


Prop	Type	Default	Description
`clearable`	`boolean`	—	Shows a clear button ("×" icon) when there is a value. Requires `reset` to work outside a `Form`.
`icon`	`any`	—	React element rendered inside the input (usually an `<Icon />`). When set, the input automatically makes room to avoid collision with the typed text. @example ```tsx <Input icon={<Icon icon={search} />} iconPosition="left" /> ```
`iconPosition`	`"right" \| "left"`	`right`	Side on which the icon (`icon` or the clear button) is rendered.
`onChange`	`((e: ChangeEvent<HTMLInputElement, Element>) => void)`	—	—
`reset`	`(() => void)`	—	Callback invoked when the user clicks the clear button (`clearable`). Inside a `Form`, it is injected automatically; in standalone use, it must clear the controlled state.
`size`	`"expansive" \| "medium" \| "compact" \| "micro"`	`medium`	Size token of the input.
`value`	`string`	—	—
`variant`	`"default" \| "success" \| "error"`	`default`	Visual variant of the input — reflects the validation state.

In addition to the props above, every component accepts the layout props (spacing, color, flex/grid, sizing, border) — not repeated here.

Theming (`theme.component.input`)

Color-wise the input sits on the surface ladder: ground surface.paper, outline edge.border, text ink.primary, placeholder and icon ink.muted; the success/error variants keep their palette for the border and make their text ink readable over the paper in each mode. Override roles per polarity with createTheme({ colors: { ladder: … } }) — see Dark Mode Engine.

The size scale is a component token: theme.component.input.size.{expansive,medium,compact,micro}, each carrying py / fontSize / borderRadius (foundation-scale keys) and height (px). Override one field of one size without forking the component:

createTheme({
  component: {
    input: {
      size: {
        medium: { py: 'small' },
      },
    },
  },
});