[field][docs] Missing usage of `Field.Item` for labelling radio and checkbox groups

[imadroshan]

Bug report

Current behavior

When composing CheckboxGroup with Field.Root and Fieldset.Root (using render={<CheckboxGroup ... />} as recommended by docs), the hidden <input type="checkbox"> elements created by Checkbox.Root end up with the same id across multiple checkboxes.

This also leads to label[for] collisions when using Field.Label (same for and same label id reused across multiple items).

This violates HTML id uniqueness rules and breaks label → control associations (and can confuse assistive tech and testing tools).

Reproducible example

import * as React from "react";
import { Field } from "@base-ui/react/field";
import { Fieldset } from "@base-ui/react/fieldset";
import { CheckboxGroup } from "@base-ui/react/checkbox-group";
import { Checkbox } from "@base-ui/react/checkbox";

export default function Repro() {
  return (
    <Field.Root name="allowedNetworkProtocols">
      <Fieldset.Root render={<CheckboxGroup defaultValue={["https"]} />}>
        <Fieldset.Legend>Allowed network protocols</Fieldset.Legend>

        {/* Version A: native label */}
        <label>
          <Checkbox.Root value="http" />
          HTTP
        </label>

        <label>
          <Checkbox.Root value="https" />
          HTTPS
        </label>

        <label>
          <Checkbox.Root value="ssh" />
          SSH
        </label>

        {/* Version B: Field.Label (also shows duplicate ids/for) */}
        {/*
        <Field.Label>
          <Checkbox.Root value="http" />
          HTTP
        </Field.Label>
        <Field.Label>
          <Checkbox.Root value="https" />
          HTTPS
        </Field.Label>
        <Field.Label>
          <Checkbox.Root value="ssh" />
          SSH
        </Field.Label>
        */}
      </Fieldset.Root>
    </Field.Root>
  );
}

Actual Results

Inspecting the DOM shows:

Version A (native )

All hidden inputs share the same id, e.g.:

<input id="base-ui-_r_1or_" ... name="allowedNetworkProtocols" />
<input id="base-ui-_r_1or_" ... name="allowedNetworkProtocols" />
<input id="base-ui-_r_1or_" ... name="allowedNetworkProtocols" />

(IDs differ per run, but within the same render they are duplicated.)

Version B (<Field.Label>)

Multiple labels share the same for and the same label element id is reused:

<label for="base-ui-_r_1s7_" id="base-ui-_r_1sh_">...</label>
<label for="base-ui-_r_1s7_" id="base-ui-_r_1sh_">...</label>
<label for="base-ui-_r_1s7_" id="base-ui-_r_1sh_">...</label>

<input id="base-ui-_r_1s7_" ... />
<input id="base-ui-_r_1s7_" ... />
<input id="base-ui-_r_1s7_" ... />

So multiple checkboxes end up referencing the same id.

Expected result

Each checkbox’s hidden <input> should have a unique id, and each label should reference the correct control.

At minimum:
no duplicate id values in the subtree
Field.Label should not generate duplicated for/id across sibling items

Why this matters

• HTML validity: duplicate IDs are invalid.
• Accessibility: label associations can be incorrect/ambiguous.
• Testing: getByLabelText, Playwright label selectors, etc. can become flaky.
• Potential UX: clicking a label may toggle the wrong checkbox depending on how associations resolve.

Base UI version

v1.1.0

Which browser are you using?

Chrome

Which OS are you using?

Windows

Additional context

Environment

• react: 19.2.0
• react-dom: 19.2.0
• @base-ui/react: 1.1.0 (please fill exact)

Notes / suspicion

This looks like an ID generation / context bug where the Field.Root name="..." + Fieldset.Root composition causes the same generated ID to be reused for multiple checkbox inputs, rather than generating per-checkbox IDs.

[mj12albert]

@imadroshan See the demo on the forms page, you may have omitted Field.Item which should enclose each item in the group:

base-ui/docs/src/app/(docs)/react/handbook/forms/demos/hero/tailwind/index.tsx

Lines 225 to 245 in 2fa5f69

	<Field.Root name="allowedNetworkProtocols">
	<Fieldset.Root render={<CheckboxGroup defaultValue={[]} />}>
	<Fieldset.Legend className="mb-2">Allowed network protocols</Fieldset.Legend>
	<div className="flex gap-4">
	{['http', 'https', 'ssh'].map((val) => {
	return (
	<Field.Item key={val}>
	<Field.Label className="uppercase">
	<Checkbox.Root value={val}>
	<Checkbox.Indicator>
	<Check className="size-3" />
	</Checkbox.Indicator>
	</Checkbox.Root>
	{val}
	</Field.Label>
	</Field.Item>
	);
	})}
	</div>
	</Fieldset.Root>
	</Field.Root>

[imadroshan]

Thanks for pointing that out — you’re right. I missed wrapping each checkbox in Field.Item.

After updating the example to include Field.Item around each checkbox/label pair, the duplicate id / for issues go away and the label associations behave as expected.

What initially confused me is that the forms docs describe Field.Item as optional for checkbox groups. In the example where it’s omitted, the markup can end up with duplicated input ids and incorrect label associations, which is what led me to think there might be a bug.

So this looks more like a usage constraint than a bug in the implementation — but it might help future users if the docs were clearer that Field.Item is effectively required when using Field-managed labels/descriptions inside a checkbox group.

Thanks for the clarification!

[mj12albert]

What initially confused me is that the forms docs describe Field.Item as optional for checkbox groups

Aha it is indeed a docs issue, some of the snippets were wrong