---
title: Field
description: Associate a control with its label, help, error, and inherited state.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Field

> Associate a control with its label, help, error, and inherited state.

Enter an invalid email and leave the input to show the error, or turn on Invalid.

## Anatomy

```text
Field [component; slot=root]
├── wrapper [slot]
│   ├── labelWrapper [slot]
│   │   ├── label [slot]
│   │   └── hint [slot]
│   └── description [slot]
└── container [slot]
    ├── help [slot]
    └── error [slot]
```

Help and error are mutually exclusive; the error replaces help while it is displayed.

## Usage

Use Field to label a standalone control and attach description, help, and error text. It registers
the nested control, passes `size`, `disabled`, `required`, and `readOnly` down to it, and wires the
ARIA relationships. It does not validate or submit values.

For schema binding, use `form.Field` from [createForm](https://moraine.subf.dev/components/form.md). Put a Moraine control
inside Field so the label, description, and error IDs attach to the actual focusable element. For
local validation, pass the current message to `error`.

Children can be JSX or a render function that receives the field state as props, such as
`(state) => ...`, where `state.error` is the effective error (`false` when `error={false}`
suppresses it).

```tsx
import { Field, Input } from 'moraine'

export function Example() {
  return (
    <Field label="Email">
      <Input name="email" type="email" />
    </Field>
  )
}
```

### Text and messages

| Prop          | Placement and behavior                                                      |
| ------------- | --------------------------------------------------------------------------- |
| `label`       | A `<label>` pointing to the nested control; also its `aria-labelledby`      |
| `hint`        | Beside the label, such as "Optional"; shown only when the field has a label |
| `description` | Under the label, above the control; linked with `aria-describedby`          |
| `help`        | Under the control; hidden while an error is displayed                       |
| `error`       | Under the control, replacing `help`; marks the control `aria-invalid`       |

When `error` is `undefined` or `null`, Field shows the error of its form binding. `error={false}`
suppresses any error, including the bound one. Empty content such as `''` displays nothing. Set
`required`, `disabled`, or `readOnly` on Field to pass the state to nested controls; a control's own
prop takes precedence. `required` also adds a required indicator to the label.

### Visually hidden labels

Use `hiddenLabel` when a compact control needs an accessible name without a visible label. It
keeps the label association without reserving label spacing or an empty horizontal label column.
A non-empty `label` takes precedence over `hiddenLabel`. Hint and description text remain visible;
help and error text keep their usual placement.

```tsx
<Field hiddenLabel="Filter commands" help="Search by command name or shortcut.">
  <Input placeholder="Filter commands…" />
</Field>
```

For a switch with a trailing visible label, use `<Switch label="Auto refresh" />`.

### Orientation

`orientation="horizontal"` lays the label beside the control, as in a settings row. `'vertical'` is
the default stacked layout.

```tsx
<Field orientation="horizontal" label="Display name" description="Shown to other users.">
  <Input />
</Field>
```

## Examples

### Hide the label on a command filter

Pass `hiddenLabel` so the input stays named without a visible label column. Help and error still
render in their usual place.

```tsx
import { Field, Input } from 'moraine'

export function HiddenLabel() {
  return (
    <div class="flex flex-col gap-4">
      <Field hiddenLabel="Filter commands" help="Search by command name or keyboard shortcut.">
        <Input placeholder="Filter commands…" />
      </Field>
      <Field
        hiddenLabel="Command prefix"
        orientation="horizontal"
        error="Enter a prefix that starts with a letter and contains no spaces."
      >
        <Input placeholder="Command prefix…" />
      </Field>
    </div>
  )
}
```

### Inherit size and required onto a switch

`size` and `required` on `Field` pass down to the nested control. Keep a visible `label` on the
switch when the field label is the setting name.

```tsx
import { Field, Switch } from 'moraine'

export function InheritedState() {
  return (
    <Field label="Notifications" size="sm" required>
      <Switch label="Email alerts" />
    </Field>
  )
}
```

### Surface a local validation message

Pass the current message to `error`. Standalone `Field` does not run a schema; your code owns the
message.

```tsx
import { Field, Input } from 'moraine'
import { createSignal } from 'solid-js'

export function ManualValidation() {
  const [error, setError] = createSignal<string | false>()
  return (
    <Field label="Username" error={error()}>
      <Input onValueChange={(value) => setError(value ? false : 'Username is required')} />
    </Field>
  )
}
```

### Align a settings row

Set `orientation="horizontal"` to put the label beside the control, as in a settings panel.

```tsx
import { Field, Input } from 'moraine'

export function HorizontalLayout() {
  return (
    <Field orientation="horizontal" label="Display name" description="Shown to other users.">
      <Input />
    </Field>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-required` | `field-label` | Present when the field input is required. |
| `data-has-text` | `field-container` | Present when the control currently contains text. |

### Props

Props for the Field component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| description | JSX.Element \| undefined | — | Description rendered under the label, above the control. It is linked to the control with<br>`aria-describedby`. |
| disabled | boolean \| undefined | — | Whether nested controls inherit a disabled state. A control's own `disabled` prop takes<br>precedence. |
| error | JSX.Element \| undefined | — | Error message rendered under the control; it replaces `help` and marks the control with<br>`aria-invalid`. When unset (`undefined` or `null`), the error of the form binding is used.<br>`false` suppresses any error, including the bound one. Empty content such as `''` or<br>`true` displays nothing. |
| help | JSX.Element \| undefined | — | Help text rendered under the control. It is hidden while an error is displayed and linked to<br>the control with `aria-describedby`. |
| hiddenLabel | string \| undefined | — | Visually hidden label used as the accessible name when `label` has no content. Ignored when<br>`label` is non-empty. |
| hint | JSX.Element \| undefined | — | Hint rendered beside the label, such as "Optional". Only shown when the field has a label<br>(visible or `hiddenLabel`). |
| id | string \| undefined | — | Prefix for the IDs of the label, hint, description, help, and error elements, which are<br>used for `aria-labelledby` and `aria-describedby`. It is not set on the root element.<br>A unique ID is generated when omitted. |
| label | JSX.Element \| undefined | — | Label for the control. Rendered as a `<label>` pointing to the nested control and used as<br>its `aria-labelledby`. Empty content (`''`, `null`, `false`) counts as no label. |
| name | Name \| undefined | — | Standalone field name, for fields not bound through `form.Field`. A string is inherited by<br>nested controls as their native `name` when they set none; a path array such as<br>`['user', 'email']` identifies the field but is not used as a native name. |
| orientation | 'vertical' \| 'horizontal' \| undefined | 'vertical' | Visual layout direction. |
| readOnly | boolean \| undefined | — | Whether nested controls inherit a read-only state. A control's own `readOnly` prop takes<br>precedence. |
| required | boolean \| undefined | false | Whether nested controls inherit the required state (`aria-required`) and the label shows a<br>required indicator. A control's own `required` prop takes precedence. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Visual size of the component. |
| as | T \| undefined | 'div' | The HTML element or component to render as. |
| children | JSX.Element \| Component<RenderProps> \| undefined | — | Content, or a render function that receives the field state as props. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |
