[docs] Add `Form` integration page #2989

mj12albert · 2025-10-16T13:34:17Z

Preview: https://deploy-preview-2989--base-ui.netlify.app/react/handbook/forms

Added a doc on how to build forms with plain Base UI and guides for React Hook Form and TanStack Form.

Also on the pages of each labelable control, added a bullet point about accessible name and linked to the new doc, it seems more space-efficient than repeating a whole snippet or demo (e.g. like Headless UI or RA).

Only added Tailwind demos, was thinking to not have CSS modules since styling is not the focus of the doc and the styling is already obscured a bit in the demos already.

Closes #21

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

pkg-pr-new · 2025-10-16T13:35:25Z

vite-css-base-ui-example

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

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

commit: 779e58f

netlify · 2025-10-16T13:36:37Z

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	`779e58f`
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/6914b6500fba230009c1666b
😎 Deploy Preview	https://deploy-preview-2989--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.

mui-bot · 2025-10-16T13:37:31Z

Bundle size report

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

Details of bundle changes

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

docs/src/app/(public)/(content)/react/handbook/forms/page.mdx

atomiks · 2025-10-21T00:10:01Z

The Toast styles should match the toast hero demo styles (e.g. swiping is selecting text in this one); also use limit={1} on the provider given it's tall. You can use [data-swipe-ignore] on parts of text that should be selectable
RHF doesn't use the re-export pattern that's used in the plain Base UI demo, but should?
Combobox checkmark styles look off compared to the hero demo styles
Group *-pattern imports together at the top as it looks cleaner than scattering them with the non-star pattern imports
The input focus visible styles should match Field hero demo
The CodeSandbox link in the top-right should have equal padding from the x/y axis, when hovering it it has less x-axis than y-axis padding from the edges of its container
Use labeling not labelling as we're following standard US/programming style English

LukasTy · 2025-11-07T11:32:25Z

docs/src/app/(public)/(content)/react/handbook/forms/page.mdx

+
+## TanStack Form
+
+[TanStack Form](https://tanstack.com/form/v1/docs/overview) is a form library with a function-based API for orchestrating validations that can also be integrated with Base UI.


WDYT about linking to the latest doc?
Or do we want to ensure the stability of the example if following majors bring significant BCs?

Suggested change

[TanStack Form](https://tanstack.com/form/v1/docs/overview) is a form library with a function-based API for orchestrating validations that can also be integrated with Base UI.

[TanStack Form](https://tanstack.com/form/latest/docs/overview) is a form library with a function-based API for orchestrating validations that can also be integrated with Base UI.

Yeah I think v1 is good for now... I'm sure v2 will have some big changes

LukasTy · 2025-11-07T14:14:46Z

docs/src/app/(public)/(content)/react/handbook/forms/page.mdx

+
+Base UI also supports [TanStack Form](https://tanstack.com/form/v1/docs/overview), which uses a function-based API to orchestrate validations.
+
+import { DemoTanstackForm } from './demos/tanstack-form';


Oh, gotcha. 👍
Then, it's only the section headings left, and even those could be left for a follow-up if they need unrelated internal changes. 👌

sss-Mihail-sss · 2025-11-07T18:04:55Z

Can you add an example of react-hook-form + zod?

docs/src/app/(public)/(content)/react/handbook/forms/page.mdx

atomiks · 2025-11-11T05:24:30Z

docs/src/app/(public)/(content)/react/handbook/forms/page.mdx

+
+import { DemoBaseUIForm } from './demos/hero';
+
+<DemoBaseUIForm showExtraPlaygroundLink />


Select trigger's and radio group's outline is 1px, not 2px like the other controls

atomiks · 2025-11-11T05:26:04Z

docs/src/app/(public)/(content)/react/handbook/forms/demos/components/checkbox.tsx

+export function Root({ className, ...props }: Checkbox.Root.Props) {
+  return (


The checkbox example used (Backup schedule) seems like a radio group not a checkbox group. Maybe another example can be used to demonstrate checkboxes?

Updated it to this:

It's quite common to have all daily/weekly/monthly backups but maybe it's not obvious... wasn't easy to find sth else from the AWS UI that can be easily oversimplified into a checkbox group (rows upon rows of ungrouped checkboxes are everywhere tho)

LukasTy · 2025-11-11T15:11:37Z

docs/src/components/QuickNav/rehypeConcatHeadings.mjs

+            if (text === 'React Hook Form' || text === 'TanStack Form') {
+              node.properties.id = `${stringToUrl(text)}-${stringToUrl(toString(node))}`;
+              break;
+            }


Have you considered going for a similar approach to Material docs, where a repeated hash is prepended with -N as in #initialize-the-form and #initialize-the-form-2 in the TanStack Forms case?

The other alternative (my biggest preference) would be to join hashes of nested headings.
Yes, that would break currently existing links in the wild, but I wager that the price to pay is not that high compared to piece of mind we'd get. 🙈 🤷

The other alternative (my biggest preference) would be to join hashes of nested headings

Yeah I think this is better than adding -N as it's more readable, but maybe it's enough to do it selectively like with this file? The other common h2s (Examples, API reference) are much more unlikely to have duplicate heading text

that would break currently existing links in the wild

We'd just have to maintain redirects like this for a very long time 😅 https://github.com/mui/material-ui/blob/master/docs/public/_redirects

Sure, no objections to going with the simple solution. 👍
We can consider abstracting it if we need to tweak this place the 3rd or 4th time. 👌

mj12albert · 2025-11-12T16:32:28Z

Can you add an example of react-hook-form + zod?

Will add schema validation related stuff in a separate PR ~

mj12albert added the docs Improvements or additions to the documentation. label Oct 16, 2025

atomiks reviewed Oct 16, 2025

View reviewed changes

docs/src/app/(public)/(content)/react/handbook/forms/page.mdx Outdated Show resolved Hide resolved

atomiks reviewed Oct 16, 2025

View reviewed changes

docs/src/app/(public)/(content)/react/handbook/forms/page.mdx Outdated Show resolved Hide resolved

atomiks reviewed Oct 16, 2025

View reviewed changes

docs/src/app/(public)/(content)/react/handbook/forms/page.mdx Outdated Show resolved Hide resolved

atomiks reviewed Oct 16, 2025

View reviewed changes

docs/src/app/(public)/(content)/react/handbook/forms/page.mdx Outdated Show resolved Hide resolved

atomiks reviewed Oct 16, 2025

View reviewed changes

docs/src/app/(public)/(content)/react/handbook/forms/page.mdx Outdated Show resolved Hide resolved

atomiks reviewed Oct 16, 2025

View reviewed changes

docs/src/app/(public)/(content)/react/handbook/forms/page.mdx Outdated Show resolved Hide resolved

mj12albert force-pushed the docs/forms-guide branch 6 times, most recently from a1de574 to 8d56a2e Compare October 18, 2025 14:28

mj12albert marked this pull request as ready for review October 18, 2025 14:49

mj12albert requested review from colmtuite and michaldudak as code owners October 18, 2025 14:49

This comment was marked as resolved.

Sign in to view

mj12albert requested review from DiegoAndai, LukasTy, atomiks, Copilot, michelengelen and mnajdova and removed request for Copilot October 19, 2025 03:26

mj12albert force-pushed the docs/forms-guide branch from 8d56a2e to 3215d45 Compare October 20, 2025 16:18

mj12albert force-pushed the docs/forms-guide branch from 4d6c5f6 to 5e47c6c Compare October 21, 2025 06:25

mj12albert added 4 commits November 7, 2025 02:58

Merge remote-tracking branch 'upstream/master' into docs/forms-guide

c9389b8

Update tanstack form

c2e03e7

Update demo

868dca2

Update docs

5f5b755

mj12albert mentioned this pull request Nov 7, 2025

[form] Documentation on the onClearErrors prop for the form component is insufficient #2758

Closed

mj12albert added 2 commits November 7, 2025 15:31

Merge remote-tracking branch 'upstream/master' into docs/forms-guide

1932638

Content

dcfdd42

LukasTy reviewed Nov 7, 2025

View reviewed changes

LukasTy approved these changes Nov 7, 2025

View reviewed changes

mj12albert added 2 commits November 8, 2025 00:46

Add server validation section

b449a43

Extra links at the top

4899281

mj12albert added 4 commits November 10, 2025 22:46

Unify and rehype h3s

9abdb44

reorder

06dc937

Merge remote-tracking branch 'upstream/master' into docs/forms-guide

9c64419

Merge remote-tracking branch 'upstream/master' into docs/forms-guide

0090127

atomiks reviewed Nov 11, 2025

View reviewed changes

docs/src/app/(public)/(content)/react/handbook/forms/page.mdx Outdated Show resolved Hide resolved

atomiks reviewed Nov 11, 2025

View reviewed changes

LukasTy reviewed Nov 11, 2025

View reviewed changes

mj12albert added 3 commits November 12, 2025 19:07

Merge remote-tracking branch 'upstream/master' into docs/forms-guide

bb3e4b2

Fixes

ca66b57

Tweak rehype

a4b3900

mj12albert mentioned this pull request Nov 12, 2025

[docs] Improve DemoTabsList when there are many tabs #3197

Open

mj12albert added 3 commits November 12, 2025 23:19

Fix misc bugs

9d75fbe

Update checkbox group example

0ede259

Merge remote-tracking branch 'upstream/master' into docs/forms-guide

779e58f

mj12albert merged commit 422a4de into mui:master Nov 12, 2025
20 checks passed

mj12albert deleted the docs/forms-guide branch November 12, 2025 16:44


		## TanStack Form

		[TanStack Form](https://tanstack.com/form/v1/docs/overview) is a form library with a function-based API for orchestrating validations that can also be integrated with Base UI.


		Base UI also supports [TanStack Form](https://tanstack.com/form/v1/docs/overview), which uses a function-based API to orchestrate validations.

		import { DemoTanstackForm } from './demos/tanstack-form';


		import { DemoBaseUIForm } from './demos/hero';

		<DemoBaseUIForm showExtraPlaygroundLink />

		export function Root({ className, ...props }: Checkbox.Root.Props) {
		return (

Uh oh!

[docs] Add Form integration page #2989

[docs] Add Form integration page #2989

Uh oh!

Conversation

mj12albert commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for base-ui ready!

Uh oh!

mui-bot commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle size report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

atomiks commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sss-Mihail-sss commented Nov 7, 2025

Uh oh!

Uh oh!

atomiks Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mj12albert commented Nov 12, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

[docs] Add `Form` integration page #2989

[docs] Add `Form` integration page #2989

mj12albert commented Oct 16, 2025 •

edited

Loading

pkg-pr-new bot commented Oct 16, 2025 •

edited

Loading

netlify bot commented Oct 16, 2025 •

edited

Loading

mui-bot commented Oct 16, 2025 •

edited

Loading

atomiks commented Oct 21, 2025 •

edited

Loading

atomiks Nov 11, 2025 •

edited

Loading