Field

Molecule
A form row: a label, the control, and one message line under it. Field exists for the part no control owns on its own: every field family already owns its label, but nothing else in the kit renders helper or error text, so that message is what Field adds.
src/molecules/field
View in Inputs

Playground

Every control sets a real prop of FieldProps. The JSX below updates as you go.
Email
Release notes only, never marketing
Props
label
string
helper
string
error
string
required
boolean
JSX · FieldProps
<Field label="Email" helper="Release notes only, never marketing" />

Variants

11 examples from src/molecules/field/field.md, each rendered live from its own JSX.
Email
Error
<Field label="Email" error="Enter a valid email address.">
<Input defaultValue="rachel.chen" />
</Field>
Email address
Email address
<Field label="Email address" error="Invalid email format.">
<Input leadingIcon icon="mail" defaultValue="exampledomain.com" keyboardType="email-address" autoCapitalize="none" />
</Field>
Password
Password
<Field label="Password" error="Password must be at least 8 characters.">
<Input leadingIcon icon="lock" secureTextEntry passwordToggle defaultValue="12345" />
</Field>
Username
Username
<Field label="Username" error="Username already taken.">
<Input leadingIcon icon="user" defaultValue="danello" autoCapitalize="none" />
</Field>
Phone number
+1
Phone number
<Field label="Phone number" error="Invalid phone number.">
<PhoneInput defaultCountry="US" defaultValue="(415) 72" />
</Field>
Date of birth
Date of birth
<Field label="Date of birth" error="You must be at least 18 years old.">
<Input leadingIcon icon="calendar" defaultValue="10/30/2020" keyboardType="numbers-and-punctuation" />
</Field>
Amount
$
Amount
<Field label="Amount" error="Invalid amount format.">
<Input prefix="$" defaultValue="128a" keyboardType="decimal-pad" />
</Field>
Email address
We only use it to sign you in.
Amount
$
Up to two decimals.
Helper text
<Column relaxed>
<Field label="Email address" helper="We only use it to sign you in.">
<Input leadingIcon icon="mail" placeholder="example@domain.com" keyboardType="email-address" autoCapitalize="none" />
</Field>
<Field label="Amount" helper="Up to two decimals.">
<Input prefix="$" placeholder="0.00" keyboardType="decimal-pad" />
</Field>
</Column>
Notifications
Release activity
Wrapping a control that keeps its own label
<Field label="Notifications">
<Switch>Release activity</Switch>
</Field>
Full name
Role
Notes
In a form
<Form>
<Field label="Full name">
<Input placeholder="Rachel Chen" />
</Field>
<Field label="Role">
<Select options={["Admin", "Editor", "Viewer"]} placeholder="Pick a role" />
</Field>
<Field label="Notes">
<Textarea rows={3} placeholder="Anything worth remembering" />
</Field>
</Form>
ZIP code
xs step, pinned to the start (320)
Street
lg step, pinned to the start (512)
City
Bare, in an lg Container: fills it (512)
Measure
<Column>
<Field xs start label="ZIP code" helper="xs step, pinned to the start (320)">
<Input placeholder="94103" />
</Field>
<Field lg start label="Street" helper="lg step, pinned to the start (512)">
<Input placeholder="1 Market St" />
</Field>
<Container lg start>
<Field label="City" helper="Bare, in an lg Container: fills it (512)">
<Input placeholder="San Francisco" />
</Field>
</Container>
</Column>

States

Hover, focus and press are pinned so they can be compared side by side; the rest are real props.
Email
Release notes only, never marketing
default
Email
Release notes only, never marketing
focus
Email
error

Anatomy

Email
Release notes only
1
Label
2
Control
3
Helper or error
4
Required mark
Dimmed parts appear only in some states or variants.

Props

7 props on FieldProps, grouped as they are declared in source. Required props are marked *.
Prop
Type
Default
Description
Props
7 props
label
string
–
Row label. When the lone child is a field-family control (Input, Textarea, Select, Autocomplete) that carries no label of its own, the label and required are DELEGATED into that control so each platform places them per its own contract. Any other control keeps the static label above.
helper
string
–
Muted hint under the control. Replaced by error when that is set.
error
string
–
Error text. Setting it puts the row in the error state: the message turns destructive and replaces helper in place, so the row never changes height and nothing below it jumps.
required
boolean
false
Marks the label with a destructive asterisk (decorative, never in an accessible name). A delegated control takes required and announces itself as required; over any other control, the label says it in its own name on iOS and Android ("Notifications, required").
children
ReactNode
–
The control.
testID
string
–
E2E hook forwarded to the root element.
style
LayoutStyle
–
Composition within a parent only, never a restyle hook and never a width: the parent layout container provides the bounds.
MeasureProps · width steps xxxs 192 · xxs 256 · xs 320 · sm 384 · md 448 · lg 512 · xl 576 · xxl 672 · xxxl 768 · wide 896 · wider 1024 · widest 1152 · page 1280, plus start to pin to the leading edge.

Accessibility and keyboard

Keyboard
Type
Edits the value
Tab
Next field
Escape
Clears when clearable
Semantics
Roles
alert
ARIA on web
aria-describedby

Platform skins

The playground's props on each platform: same tree, native shapes, type and touch sizes.
Email
Web
control 10 · field 10 · card 16 · Instrument Sans
Email
iOS
capsule controls · field 8 · card 12 · SF Pro · 44 pt
Email
Android
Material 3 stadium · field 4 · card 12 · Roboto · 48 dp

Usage

<Field label="Email" helper="We'll never share your email.">
<Input placeholder="you@example.com" />
</Field>
When the row wraps a single field-family control that has no label of its own, Field hands the label down to it rather than drawing one alongside, so each platform still places it its own way: a static title above on web and iOS, the floating in-container label on Android, and required goes down with it. Over any other control (a Switch, a group) Field draws the label above with its star, and on iOS and Android the label says "required" in its own name. Set error and it replaces helper in the same slot, so the row never changes height and nothing below it jumps; on the web an error leads with a small alert glyph.

Tokens

Read from the playground render. Values follow the scheme and the ion hue.
--bg2
--fd
--ft
--ln2
--tx2
--tx3

Related components