A structural layout container that groups related form controls under a native <fieldset>, complete with an accessible legend, supporting helper text, and validation error messages. It serves as an essential semantic anchor for complex user input forms, automatically propagating disabled, invalid, and required statuses down to nested field controls.

Usage

These examples illustrate how content editors bind and structure fieldset groups.

1. Standard Account Information Group

A standard user profile group with mandatory nested name fields. Features an active legend and helper status text.

{
  "type": "fieldset",
  "legend": "Account Information",
  "helperText": "Configure your primary account details.",
  "required": true,
  "children": [
    {
      "type": "field",
      "label": "Full Name",
      "placeholder": "Jane Doe",
      "interactive": true
    },
    {
      "type": "field",
      "label": "Email Address",
      "placeholder": "jane@example.com",
      "interactive": true
    }
  ]
}

2. Invalid Group with Error Message

Showcases how the Fieldset displays validation error messages when a grouping requirement is violated. Entering an errorText automatically triggers invalid states on all child fields.

{
  "type": "fieldset",
  "legend": "Billing Credentials",
  "helperText": "Enter your card billing details.",
  "errorText": "A valid postal code is required.",
  "children": [
    {
      "type": "field",
      "label": "Cardholder Name",
      "placeholder": "Jane Doe",
      "interactive": true
    },
    {
      "type": "field",
      "label": "Postal Code",
      "placeholder": "90210",
      "invalid": true,
      "interactive": true
    }
  ]
}

3. Disabled Billing Options Block

Demonstrates a fully disabled shipping parameters section. Deactivating the parent Fieldset automatically locks every nested element.

{
  "type": "fieldset",
  "legend": "Shipping Address",
  "helperText": "Unavailable during local holidays.",
  "disabled": true,
  "children": [
    {
      "type": "field",
      "label": "Street",
      "placeholder": "123 Main St",
      "interactive": true
    },
    {
      "type": "field",
      "label": "Apt #",
      "placeholder": "4B",
      "interactive": true
    }
  ]
}

Props

Developer Notes & Accessibility

• Hydration Free (Static-Only): Fieldset is a semantic layout component designated as a Static-Only component (Tier 3). It renders entirely as standard server-side HTML and is exempt from client-side hydration scripts.
• Context Propagation: It utilises context providers to propagate disabled, invalid, and required states downward. Direct child component blocks (such as Field and Textarea) automatically listen to this context and inherits group properties, eliminating duplicate key declarations.
• WAI-ARIA Compliance: Fieldset compiles strictly to semantic HTML <fieldset> containers containing direct <legend> elements, satisfying accessible browser heading requirements.