[field][docs] Update Field.Item related docs

[mj12albert]

Closes #3807

• I have followed (at least) the PR section of the contributing guide.

[pkg-pr-new]

• base-ui-tanstack-start

• vite-css-base-ui-example

  pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/react@3809
  

  pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/utils@3809
  

commit: 8a260ab

[mui-bot]

Bundle size report

Bundle	Parsed size	Gzip size
@base-ui/react	0B(0.00%)	0B(0.00%)

Details of bundle changes

---

Check out the code infra dashboard for more information about this PR.

[netlify]

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	8a260ab
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/697358f8c44bfc00085ae58f
😎 Deploy Preview	https://deploy-preview-3809--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[greptile-apps]

Greptile Summary

This PR fixes a critical documentation bug where Field.Item was missing from checkbox and radio group examples. Without Field.Item, each control within a group would incorrectly share the same generated ID, violating HTML uniqueness rules and breaking label associations. The changes add Field.Item wrappers around each individual checkbox/radio in the documentation examples for:

• Checkbox Group component page - wrapped each Field.Label containing a checkbox
• Radio component page - wrapped each Field.Label containing a radio
• Forms handbook - clarified that Field.Item "should enclose" each item

The updated documentation now matches the correct usage pattern shown in the codebase tests, where Field.Item provides the LabelableProvider context needed to generate unique IDs for each control.

Confidence Score: 5/5

• This PR is safe to merge with no risk - it only corrects documentation
• The changes are documentation-only and fix a critical issue where examples showed incorrect usage that would cause duplicate IDs. The updated code matches the established patterns in test files and resolves the reported bug.
• No files require special attention

Important Files Changed

Filename	Overview
docs/src/app/(docs)/react/components/checkbox-group/page.mdx	Updated documentation to correctly show Field.Item wrapping each checkbox in group examples, fixing the duplicate ID issue
docs/src/app/(docs)/react/components/radio/page.mdx	Updated documentation to correctly show Field.Item wrapping each radio in group examples, ensuring proper ID generation
docs/src/app/(docs)/react/handbook/forms/page.mdx	Updated forms handbook to clarify that Field.Item should enclose each item in checkbox/radio groups

[atomiks]

Curious why (implementation wise) this is necessary? Is there a way to avoid it for the enclosing case?

All the other component docs about labeling would also need to be updated here as they omit <Field.Item>

[mj12albert]

IIRC it's because we changed from <button> to spans so even for enclosing labels htmlFor needs to be set explicitly

Is there a way to avoid it for the enclosing case?

Could possibly make Field.Label render Field.Item internally when necessary? 🤔

All the other component docs about labeling would also need to be updated here

This is only relevant for checkbox group and radio group though

[atomiks]

IIRC it's because we changed from to spans so even for enclosing labels htmlFor needs to be set explicitly

What does the htmlFor do though when enclosed? IIRC the input becomes the label focus target when enclosed, which redirects focus to the <span>, so it works anyway. And when focus is on the <span>, the label text is still announced to screen readers (as it works with native <label> as well)

[mj12albert]

It seems intentional since all the tests were updated to have FieldItem in all cases, perhaps it can be omitted for enclosing FieldLabels as long as it doesn't trigger any chrome errors

Update: it works but does indeed cause duplicate id errors in Chrome #3815 (comment) @atomiks

[atomiks]

Alright, let's update the relevant docs to use <Field.Item> then