Field

Usage examples

import { Field, FieldDescription, FieldLabel, NativeSelect } from '@rookcom/monarch-react';

const TIMEZONES = [
  { value: 'UTC', label: 'UTC' },
  { value: 'Europe/London', label: 'London' },
  { value: 'Asia/Kolkata', label: 'Kolkata' },
  { value: 'America/New_York', label: 'New York' },
];

<Field required>
  <FieldLabel>Time zone</FieldLabel>
  <NativeSelect options={TIMEZONES} placeholder="Choose a time zone" defaultValue="" />
  <FieldDescription>Used for reminders and reports.</FieldDescription>
</Field>

import { NativeSelect } from '@rookcom/monarch-react';

const SORTS = [
  { value: 'updated', label: 'Last updated' },
  { value: 'created', label: 'Newest' },
  { value: 'priority', label: 'Priority' },
];

<NativeSelect size="sm" label="Sort" options={SORTS} defaultValue="updated" />

import { useState } from 'react';
import { Field, FieldDescription, FieldLabel, Switch } from '@rookcom/monarch-react';

function DigestRow() {
  const [on, setOn] = useState(true);
  return (
    <Field layout="row">
      <FieldLabel>Weekly digest</FieldLabel>
      <FieldDescription>A summary of activity, sent on Monday mornings.</FieldDescription>
      <Switch checked={on} onCheckedChange={setOn} />
    </Field>
  );
}

<DigestRow />

Purpose

Groups a label, one form control, help text and an error message, and wires their ids and ARIA attributes together so every Monarch control is labelled and described correctly.

Design principles

• Wiring is automatic: the control receives id, aria-describedby, aria-invalid, aria-required and disabled from the Field.
• aria-describedby only names parts that are rendered: FieldDescription and FieldError register themselves.
• Explicit props on the control always win, so controls also work outside a Field.
• FieldError can always be present: it renders nothing when its children are empty.
• NativeSelect is the real <select>: it keeps the platform picker, form submission and typeahead, and only restyles the closed control.
• Layout is a prop, not a new component: layout="row" rearranges the same parts.

API reference

import { Field, FieldDescription, FieldError, FieldLabel, NativeSelect, useFieldContext, useFieldControl } from '@rookcom/monarch-react';

Field renders a <div class="mn-field"> and provides context; FieldLabel forwards its ref to the <label>.

useFieldControl(props, { invalid }) merges Field context into a control’s props; useFieldContext() returns the raw context, or null outside a Field.

NativeSelect forwards its ref to the <select>; all native select attributes pass through. It renders <span class="mn-native-select"> around the select and its chevron.

Generated from the TypeScript declarations of packages/react/src/components/forms/form-field.

Properties

Field id overrides the generated control id; the label, description and error ids derive from it (<id>-label, <id>-description, <id>-error).

Variants

States

Interaction behaviour

• Clicking the label focuses the control (htmlFor points at the control id).
• When validation changes, FieldError registers and unregisters itself, so aria-describedby and aria-invalid update with it.
• FieldError is an aria-live="polite" region, so a new message is announced.
• NativeSelect opens the platform picker; clicking its inline label focuses it.

Keyboard support

Field adds no key handling of its own. Keyboard behaviour is the control’s; the label is reachable by clicking only.

Accessibility

Role

–

Accessible name

FieldLabel, linked to the control with htmlFor.

• The control is described by FieldDescription and, while invalid, FieldError, in that order.
• The required asterisk is aria-hidden; aria-required carries the meaning.
• Select trigger receives aria-required but not required, which is invalid on a button.
• Ids come from useId, so they are stable between server and client render.
• NativeSelect is a real <select> (role combobox or listbox by browser), so screen readers announce it natively. Outside a Field, give it label or aria-label.
• The chevron is decorative (aria-hidden).

Responsive behaviour

• A vertical stack (label, control, help, error) that fills its container at every width.
• layout="row" keeps the control on the right at every width; the text column shrinks and wraps first (minmax(0, 1fr)).
• NativeSelect fills a stacked Field; on its own it is inline and shrinks with an ellipsis rather than overflowing.

Theme support

• Label, help and error colours are semantic tokens (--mn-color-text-*, --mn-color-danger-strong), so they follow light, dark and more-contrast themes.
• The error colour does not change with the product accent.
• NativeSelect reuses the Input surface, border and focus tokens; the open picker is drawn by the platform and follows color-scheme.

Do and don't

Related components

• Input: Input and Textarea, the most common Field controls.
• Select: Single-value picker that reads Field context.
• Combobox: Searchable picker that reads Field context.
• SettingsSection: SettingsRow builds on Field for settings pages.
• Switch: The control in a layout="row" switch row.
• SwitchSettingsList: A list of switch rows that each save on their own, with saving and error states.

Dependencies

Testing coverage

• Wires label, description and error to the control (required, aria-invalid, accessible description).
• Only references descriptions that exist.
• Adds and removes the error reference as validation changes.
• Propagates disabled to the control.
• Works in StrictMode (double effects).
• Text-field tests prove explicit props win outside a Field; Select tests prove a trigger gets aria-required, not required.
• NativeSelect: Field wiring (name, description, error, required), disabled placeholder and options, uncontrolled and controlled changes, inline label naming and focus, Tab focus, disabled from Field.
• layout="row" labels and describes a Switch, the label toggles it, and the default stacked markup has no data-layout.

Tests: packages/react/src/components/forms/form-field