Recommended pattern for nesting <form> inside a parent FieldSet > FieldGroup layout?

[hadikman]

Hi everyone 👋

I'm working with the new Field components (FieldSet, FieldGroup, FieldLegend, FieldDescription, Field) and I'm running into a nesting issue when a child component needs its own <form> element inside a parent FieldSet > FieldGroup layout.

The expected hierarchy

As I understand it, the correct order is:

<form>
  └─ FieldSet
      └─ FieldGroup
          └─ Field

The problem

I have a page-level FieldSet that acts as a layout grid. One of its children (AddFeatureValue) contains its own <form>, which breaks the nesting chain:

// UpdateFeaturePage.tsx
<FieldSet>
  <FieldLegend>Edit Feature</FieldLegend>
  <FieldDescription>Fill value field</FieldDescription>

  <FieldGroup className="lg:grid lg:grid-cols-[1fr_var(--container-xs)]">
    {/* This child contains a <form> internally ⬇️ */}
    <FeatureValues featureData={featureData} />

    <Card>
      {/* ... FeatureProperties ... */}
    </Card>
  </FieldGroup>
</FieldSet>

// FeatureValues.tsx
<FieldGroup>
  <AddFeatureValue featureData={featureData} />
  {/* ... table / empty state ... */}
</FieldGroup>

// AddFeatureValue.tsx
<form id="add-value-form" onSubmit={e => e.preventDefault()}>
  <FieldGroup>
    <form.AppField name="value">
      {field => <field.TextField label="Value" />}
    </form.AppField>

    <Field className="sm:w-max">
      <form.AppForm>
        <form.SubscribeButton form="add-value-form" label="Add" />
      </form.AppForm>
    </Field>
  </FieldGroup>
</form>

This results in a broken hierarchy:

FieldSet                         ← page-level
 └─ FieldGroup                   ← page-level grid
     └─ FieldGroup               ← FeatureValues (redundant?)
         └─ <form>               ← ❌ breaks the chain
             └─ FieldGroup
                 └─ Field

What I tried

I moved <FieldSet> inside the <form> to restore the correct order:

<form id="add-value-form" onSubmit={e => e.preventDefault()}>
  <FieldSet>
    <FieldGroup>
      {/* fields... */}
    </FieldGroup>
  </FieldSet>
</form>

And removed the redundant <FieldGroup> wrapper in FeatureValues. This gives:

FieldSet                         ← page-level
 └─ FieldGroup                   ← page-level grid
     ├─ form
     │   └─ FieldSet             ← ✅ restores order
     │       └─ FieldGroup
     │           └─ Field
     └─ Card

This works, but I'm not sure if nesting a FieldSet inside a parent FieldGroup is the intended pattern.

Questions

1. Is form → FieldSet → FieldGroup → Field a strict requirement, or is it more of a semantic/a11y recommendation?
2. What is the recommended pattern when a child component inside a FieldSet > FieldGroup layout needs its own <form> element? Should each form own its own FieldSet, or is there a better approach (e.g., using form attribute on fields to associate them with an external form)?
3. Is nesting FieldSet inside FieldGroup (as in my workaround) considered valid, or does it have unintended side effects for accessibility / styling?

Any guidance or examples would be greatly appreciated. Thanks! 🙏

[morvayo]

that order is not a strict component tree requirement FieldSet renders a native fieldset and FieldGroup is a layout div so a form inside a group is valid as long as there is no ancestor form your child form owning its own FieldSet is fine for this page i would use a plain div or section for the outer grid and keep FieldSet plus FieldLegend inside each actual form so unrelated card controls are not grouped under the add value legend watch the direct child styling though since wrapping a FieldGroup in a form changes which spacing selectors match component source

[croxln]

To answer your three questions directly based on HTML5 specifications and component composition in React:

1. Is orm > FieldSet > FieldGroup > Field a strict hierarchy?

No, it is a semantic and accessibility recommendation, not a strict component constraint.

Under the hood in shadcn/ui:

• renders a native element.
• renders a
  layout container.
• renders an accessible wrapper for a control and its label/description/error.

The single hard constraint in HTML is that

elements cannot be nested inside another . Because your page-level layout does not have an outer , placing a inside a layout container like FieldGroup is completely valid HTML.

---

2. Recommended pattern when a child needs its own form

There are two clean ways to structure this:

Approach A: Invert Layout & Form Ownership (Recommended)

Use standard layout primitives (

or

with grid classes) for the page-level two-column layout, and let each functional component own its own and internal :

` sx
// UpdateFeaturePage.tsx

Edit Feature

Manage feature configuration and values

{/* FeatureProperties */}

`

` sx
// AddFeatureValue.tsx

Feature Values Add acceptable values for this feature

<FieldGroup>
  <form.AppField name="value">
    {field => <field.TextField label="Value" />}
  </form.AppField>

  <Field className="sm:w-max">
    <Button type="submit">Add</Button>
  </Field>
</FieldGroup>

` *Why this is better:* In accessibility trees (screen readers), a defines the context for all controls inside its . If you put the entire page grid under one , controls inside Card get implicitly grouped under "Edit Feature / Fill value field", which is confusing for assistive tech.

Approach B: HTML5 orm attribute decoupling

If visual styling requires

to wrap the entire container, you can declare outside or at the root, and associate inputs via the native orm="add-value-form" attribute:

` sx

{/* Inside AddFeatureValue, link inputs directly */} Add `

---

3. Is nesting FieldSet inside FieldGroup valid?

Yes, nesting

inside

or vice-versa is valid HTML5.

The only caveat to keep in mind is Tailwind direct-child spacing: if your parent uses direct child selectors ([&>*] or space-y utilities), adding an unstyled wrapper between elements can break margin collapsing or flex gap alignment unless you apply display: contents:

` sx

... `

Approach A (inverting the boundary so each form owns its own FieldSet) is the cleanest, most maintainable, and matches how component libraries design multi-form administrative pages.

[jorgehaf]

Agree the order isn't enforced: none of these components read context from each other. FieldSet is a plain <fieldset> and FieldGroup is a <div> with classes. But some of those classes depend on DOM structure, and that's where a <form> in between changes things. From field.tsx:

// FieldGroup
"group/field-group @container/field-group flex w-full flex-col gap-7 ... [&>[data-slot=field-group]]:gap-4"

1. Spacing of nested groups. A FieldGroup that is a direct child of another one gets gap-4 instead of gap-7. With a <form> (or a FieldSet) in between, the selector no longer matches, so the inner group goes back to gap-7. display: contents on the form doesn't fix this: it changes layout, but child selectors still see the <form> in the DOM. If you want the nested spacing, set it on the inner group: <FieldGroup className="gap-4"> (cn merges it over gap-7).

2. Responsive fields measure the nearest group. Every FieldGroup is a container (@container/field-group). <Field orientation="responsive"> switches to a row at @md/field-group, measured against the closest FieldGroup. In your grid that's the column (or the group inside the form), not the page. Usually what you want, but it explains why the same field can look different inside and outside the form.

3. disabled cascades through <fieldset>. If you ever disable the page-level FieldSet (while saving, for example), every control inside it is disabled too, including the inner form's input and submit button. That's native fieldset behavior.

4. Nested legends get announced. When focus enters a field, screen readers can read the legend of each enclosing <fieldset>, so "Edit Feature" is also read before the inner form's fields.

Because of 3 and 4, I'd use a plain <div>/<section> for the page grid and let each <form> own its FieldSet + FieldLegend. With that, nesting a FieldSet inside a FieldGroup is fine; only 1 and 2 still apply.