# Mode field
> Generated from mode-field.contract.json — do not edit by hand.

A labelled field with an inline exclusive mode control whose body swaps in place — the settings field for a control that has two-or-more mutually-exclusive modes.

Tier: **leaf-lit**. Frameworks: HTML (paste-and-run, no build step) · React · Vue 3.

Surfaces: editor, settings.

## Props
| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `label` | string | `—` | The field label, left of the mode control |
| `options` | Array<{value,label,icon?}> | `[]` | The exclusive modes; set as a property or a JSON attribute (alias: modes) |
| `value` | string | `—` | The active option's value (alias: mode) |
| `variant` | 'radio' | 'segmented' | `'radio'` | radio = outline segmented (brand border, white fill); segmented = neutral grey |
| `labelVariant` | 'field' | 'section' | `'field'` | field = regular weight; section = semibold header for a grouped-list body (attr: label-variant) |
| `help` | string | `—` | When set, a "?" tooltip after the label (icon system-question-mark) |
| `disabled` | boolean | `false` | Non-interactive; grey buttons |
| `change` | CustomEvent<{value}> | `—` | Composed event on change; read e.detail.value (e.detail.mode is a back-compat alias) |

## Visual standard (measured)
- Head: label LEFT / mode control RIGHT on one row; gap 12, wraps (row-gap 8) on narrow; 32 min-height
- Radio variant (default): OUTLINE segmented, 32 high, semibold 13; selected = #6A1EBB border + #6A1EBB text on WHITE fill (no tint pill)
- Segmented variant: neutral grey control — #F7F7F7 track, secondary-grey labels, active = white raised on default-text
- Label variant: field = regular 400; section = semibold 600 (a header for a grouped-list body)
- Help: optional "?" tooltip (system-question-mark) after the label when `help` is set; opens below (bottom-start) so it clears the panel top, and the bubble wraps within 240px
- Body: the active value's light-DOM child; others hidden in place (persistent, keep state); margin-top 12; de-emphasised help text — secondary #4A4A4A, 13/20, regular — so the label stays the field's primary line
- Hover: #D3B4FF border + #6A1EBB label on a radio-variant button
- Disabled: #F1F1F1 fill, #EBEBEB border, not-allowed

## When to use
- **Mode field** — a single setting whose control has 2+ exclusive modes and a mode-specific body (automatic vs manual, value-source A vs B)
- **Segmented** — an exclusive choice with NO mode-specific body to swap
- **Switch** — a plain immediate on/off with no modes

Only the active value's body is live — the others stay in the DOM (persistent) but hidden, so switching back restores their state. Default `variant='radio'` is an OUTLINE segmented control (brand border + brand text on white); a solid brand-filled pill is NOT the mode-field look — pick `variant='segmented'` for the neutral grey alternative. A mode toggle for an action may keep a verb-led label ('Show results manually') per SETTINGS-01.