# Field

Package: @nannier/canvas
Version: 4.7.1
Status: source-snapshot (not proof of an npm release)
Source SHA-256: de5ea526b4ae19d482b04b65f85a075689ab39c3ee20ffbdd9b8d3b1cde8ffaf

Source: `src/molecules/field/field.md`
Human reference: https://canvas.nannier.com/components/field

## Public imports

```tsx
import { Field } from "@nannier/canvas";
```

The following examples are source excerpts. Supply application data and handlers; snippets using `tokens` read `const { tokens } = useTheme()` inside a component. Import React hooks from React. Intentional “Don't” examples illustrate unsupported patterns.

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.

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.

## Usage

```tsx
<Field label="Email" helper="We'll never share your email.">
  <Input placeholder="you@example.com" />
</Field>
```

## Variants

### Error

```tsx
<Field label="Email" error="Enter a valid email address.">
  <Input defaultValue="rachel.chen" />
</Field>
```

### Email address

```tsx
<Field label="Email address" error="Invalid email format.">
  <Input leadingIcon icon="mail" defaultValue="exampledomain.com" keyboardType="email-address" autoCapitalize="none" />
</Field>
```

### Password

```tsx
<Field label="Password" error="Password must be at least 8 characters.">
  <Input leadingIcon icon="lock" secureTextEntry passwordToggle defaultValue="12345" />
</Field>
```

### Username

```tsx
<Field label="Username" error="Username already taken.">
  <Input leadingIcon icon="user" defaultValue="danello" autoCapitalize="none" />
</Field>
```

### Phone number

```tsx
<Field label="Phone number" error="Invalid phone number.">
  <PhoneInput defaultCountry="US" defaultValue="(415) 72" />
</Field>
```

### Date of birth

```tsx
<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

```tsx
<Field label="Amount" error="Invalid amount format.">
  <Input prefix="$" defaultValue="128a" keyboardType="decimal-pad" />
</Field>
```

### Helper text

```tsx
<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>
```

### Wrapping a control that keeps its own label

```tsx
<Field label="Notifications">
  <Switch>Release activity</Switch>
</Field>
```

### In a form

```tsx
<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>
```

### Measure

```tsx
<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>
```

## Do & Don't

### The message line

**Do** — Put helper and error text on the Field, so the row owns one message slot and the type and
color stay right in both states.

```tsx
<Field label="Email" error="Enter a valid email address." required>
  <Input value="rachel.chen" />
</Field>
```

**Don't** — Stack a raw Text under the control: it drifts from the caption scale, misses the
destructive tone, and is never announced as an error.

```tsx
<Column tight>
  <Input label="Email" required value="rachel.chen" />
  <Text style={{ fontSize: 12, color: "#e7000b" }}>Enter a valid email address.</Text>
</Column>
```

### The label

**Do** — Let Field hand the label to the control it wraps,
so Android can float it inside the box.

```tsx
<Field label="Email">
  <Input placeholder="you@example.com" />
</Field>
```

**Don't** — Label the control from outside with your own Text: the label can never float, and the
tap target no longer includes it.

```tsx
<Column tight>
  <Text style={{ fontSize: 14, fontWeight: "500" }}>Email</Text>
  <Input placeholder="you@example.com" />
</Column>
```

## Accessibility

A single Input, Textarea, Select, Autocomplete or PhoneInput receives Field's required and error state even when it already has a label or Field has no label. Explicit child `label`, `required` and `error` values take precedence, including `false` for either state. Label delegation only changes where the label is drawn.

The active helper or error message is added to the control's existing `aria-describedby` IDs. Errors use the alert role. Native controls receive the message as `accessibilityHint`; an explicit child hint takes precedence. These relationships update when validation changes. Multiple children and other control types keep their own validation and description wiring.

## Supported props

### FieldProps

Includes `MeasureProps`; their supported fields are expanded below.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | string \| undefined | no |  | Row label. When the lone child is a field-family control (Input, Textarea, Select, Autocomplete, PhoneInput) that carries no `label` of its own, the label is delegated into that control so each platform places it per its own contract. Validation and descriptions reach that single control even when it owns its label or Field has no label. |
| helper | string \| undefined | no |  | Muted hint under the control. Replaced by `error` when that is set. |
| error | string \| undefined | no |  | 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 \| undefined | no | 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 | no |  | The control. |
| testID | string \| undefined | no |  | E2E hook forwarded to the root element. |
| style | LayoutStyle | no |  | Composition within a parent only, never a restyle hook and never a width: the parent layout container provides the bounds. |
| xxxs | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| xxs | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| xs | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| sm | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| md | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| lg | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| xl | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| xxl | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| xxxl | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| wide | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| wider | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| widest | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| page | boolean \| undefined | no | false | Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge. |
| start | boolean \| undefined | no | false | Pin a capped component to the leading edge instead of centering it in its column. |

See [installation](https://canvas.nannier.com/ai/4.7.1/installation.md) for required peers and feature fallbacks.
