Forms

Input

stable

Since 1.2

Single-line text entry, with TextField for labelled fields and InputGroup for adornments, prefixes, and attached controls.

Forms

primitive

Form Control

Needs State Matrix

import { Input } from '@ivim/native/components';

When to use

Use when

Someone needs to enter or edit a short piece of free text.

A value needs framing — a currency symbol, a unit, a domain suffix — in which case use InputGroup.

Don't use when

The text runs to multiple lines — use TextArea, which adds a counter and a growth policy.

The value comes from a fixed set — use Select.

You need a labelled field with an error; reach for TextField rather than wiring Input by hand.

Playground

Adjust the controls to preview live prop combinations. The code snippet updates to match the current selection.

Email address

variant

default

glass

size

Required

isRequired

Read only

isReadOnly

Disabled

isDisabled

Label

label

<TextField label="Email address" />

Example

Preview

Code

TextField

Default

Email address

Required, with description

Email address

We only use this for receipts.

With an error

Email address

Enter a valid email address

With a tooltip

Email address

Read only (still selectable)

Disabled

Sizes (sm, md, lg)

Small

InputGroup composition

Leading icon

Prefix and suffix

https://

.com

Leading addon

Trailing action

Invalid (state flows to the field)

Disabled (state flows to the field)

Anatomy

The parts that compose this component.

Label

Field name. Also becomes the control’s accessible name.

Required marker

Asterisk beside the label; also folded into the accessible name.

Input

The editable control, carrying the border, fill, and focus ring.

Description

Helper text, replaced by the error when one appears.

Error

Announced as an alert and appended to the accessible name.

Group frame

InputGroup only — owns the border and hosts leading/trailing/addon slots.

Guidelines

Prefer TextField over a bare Input: it associates the label, requirement, and error with the control, which React Native will not do for you.

Set isReadOnly rather than isDisabled for a value someone should still be able to read and copy.

Configure state on InputGroup, not on the field inside it — the group pushes size, invalid, and disabled down so the two cannot disagree.

Don't

Use a bare Input with a separate label element; without an accessibilityLabel the field announces as an unnamed text box.

Don't

Use placeholder text as the label — it disappears the moment someone types.

Props

Public props for this component. Required props are marked; defaults reflect the component implementation.

isDisabled

boolean

default: false

Dims the field, blocks interaction, and announces disabled.

isReadOnly

boolean

default: false

Blocks editing but keeps the value focusable and selectable, and announces as enabled.

isInvalid / isRequired

boolean

default: false

Error treatment and required marker; both reach assistive tech.

size

'sm' | 'md' | 'lg'

default: 'md'

Height, padding, and text scale.

TextField: label / description / errorMessage

ReactNode

Field anatomy. Label and error are folded into the accessible name.

TextField: tooltip

string

Contextual help behind a small info affordance beside the label. Supplementary only — anything required to act belongs in description.

InputGroup: leading / trailing

ReactNode

Elements inside the frame, before and after the field.

InputGroup: prefix / suffix

string

Static text such as "https://" or a unit.

InputGroup: addonLeading / addonTrailing

ReactNode

Attached controls on either edge, against a tinted fill and a hairline.

isEmbedded

boolean

default: false

Suppresses the field’s own border and background. Set automatically by InputGroup so a composed field renders one shared frame.

Deviations from Untitled UI

Where this component deliberately differs from Untitled UI's API, and why. These are kept choices, not gaps to close.

Untitled UI

`hint?: ReactNode` doubling as error text when invalid

Ours

`description` + `errorMessage`

UUI's `hint` is a UUI-ism layered over React Aria, which itself uses `description`/`errorMessage`. We follow the substrate; both slots can render simultaneously.

Accessibility

Roles and screen-reader behavior this component provides, plus keyboard interactions.

•

React Native has no aria-labelledby, so TextField forwards its label text as the input’s accessibilityLabel — without it a labelled field still announces as unnamed.

•

There is no aria-describedby either, so the required marker and error text are appended to the accessible name rather than left unattached.

•

aria-invalid and aria-required are emitted only when true; a false flag on every field is noise.

•

Read-only announces as an enabled control and stays selectable; disabled announces as unavailable.

•

The web focus ring is inset (outlineOffset -2), matching PressableFeedback, so InputGroup’s overflow-hidden frame never clips it.

Tab

Moves focus into and out of the field.

Any character

Edits the value, unless read-only or disabled.