[docs] New props table #2135

mj12albert · 2025-06-18T14:43:01Z

Preview: https://deploy-preview-2135--base-ui.netlify.app/react/components/toggle

Uses native <details>+<summary> for the new props table design; also applies to CSS vars and data attrs tables where the popover is replaced with a <details>.

Notable differences from Accordion:

VO reads the trigger as "disclosure triangle, group" in Chrome, "summary, group" in Firefox and Safari; overall it's a bit shorter because it doesn't have a heading element adding to the announcement
Can't arrow between triggers like Accordion but is lightly reimplemented here
It's hidden="until-found" by default when supported, no need to fight React 👍

Closes #1752

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

pkg-pr-new · 2025-06-18T14:44:10Z

vite-css-base-ui-example

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

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

commit: 5457b8c

mui-bot · 2025-06-18T14:44:20Z

Bundle size report

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

Details of bundle changes

Generated by 🚫 dangerJS against 5457b8c

netlify · 2025-06-18T14:45:54Z

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	`5457b8c`
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/6886cdb8da51550008644f3d
😎 Deploy Preview	https://deploy-preview-2135--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.

docs/src/components/Accordion.tsx

romgrk · 2025-06-18T16:13:14Z

docs/src/components/ReferenceAccordion/PropsReferenceAccordion.tsx

+  if (['boolean', 'string', 'number'].includes(type)) {
+    return type;
+  }


Same as above. The [...].includes(...) syntax is bad for performance

For now this is just a throwaway ~
But should we generate the short prop type here or via the api extractor? @michaldudak

If API extractor returns an IntrinsicNode, we should use it as is.

If the returned type has both the name an either types (like a union or intersection) or properties (object type), use the name as a short type and drill into the details for the expanded view.

romgrk · 2025-06-24T20:48:45Z

docs/src/components/ReferenceTable/PropsReferenceAccordion.tsx

I wonder if we should avoid repeating the default value in the expanded details. It adds noise if we repeat information, and noise is not great for UX.

And I wonder if we shouldn't mark the Type in the expanded details as something like Type (detailed), or inversely mark the column header as Type (simplified), to convey that there's possibly more information in the expanded details.

if reducing noise is the goal, then I would remove the default from the summary and only have it in the panel.

In the screenshot below, the visual noise is coming from the repetition of the word "default".

So I see 3 options:

Remove the default from the summary, and just have it in the expanded panel. Of course, the trade-off is that you can't see the default at a glance.

Add a new column for default.

Just leave it as-is.

Sounds like a worst UX, there's less information available without clicking. When I refer to a props table, it's nice to be able to keep it open as a reference while I write code and see everything at a glance.

That's the way it was before, and it left less place for the type description, and in some cases it was nearly all empty. Tbh I suggested merging type & default in a single column because I was hoping to have more space to show the type, but now that long function types are always simplified to function and hidden, it's less relevant, but imho hidding the function types isn't necessary.

Doesn't feel too bad. We could also find a terser notation, e.g. name the column Type [Default] and use values like boolean [false]. Or integrate the default to the name column, e.g. defaultChecked = false, but we have a lot of unused space in the type column.
edit: Or boolean [=false], somewhat similar to jsdoc's [name=default] notation.

Sidenote but there's still default: undefined entries, we should not display the default if there is none or if it's undefined.

romgrk · 2025-06-24T20:53:45Z

docs/src/components/ReferenceTable/PropsReferenceAccordion.tsx

+              <TableCode className="text-navy">{name}</TableCode>
+              {prop.type && (
+                <span className="flex items-baseline gap-4 text-sm">
+                  <ShortPropType />


I'm on the fence about hiding the detailed type in the details in some cases. For render & className it makes sense to always hide it, but for other cases (like below) I think it might degrade the UX a bit to have to click to see the full type. I wonder if we could try to hide it based on its length.

The full type is available in a tooltip

Nice for mouse users, but keyboard-centric users (which are probably higher in proportion among devs) don't have that, and requiring a hover is not that far from requiring a click. I still think we should use the space if we have the space.

romgrk · 2025-06-24T21:09:24Z

docs/src/components/DescriptionList.css

I played a bit with the styling, sharing in case it inspires you to change things a bit. Imho the current box-shadow is too intense.

Before After

CC @colmtuite , this continues from #2120 (comment)

I toned down the shadow, but there's still the issue of the open panel background being very similar to the hover state of the trigger

mj12albert · 2025-06-30T02:54:02Z

Needs #2104 to generate the json in the new format

atomiks · 2025-07-03T09:07:27Z

Seems like it shouldn't open while trying to select text. (The Accordion example made this impossible, but that's not accessible)

Screen.Recording.2025-07-03.at.7.06.44.pm.mov

mj12albert · 2025-07-07T08:53:12Z

Seems like it shouldn't open while trying to select text

When clicking the text selection, should it cancel the text selection only or toggle the element as well?

Screen.Recording.2025-07-07.at.4.47.18.PM.mov

Or should we use user-select:none for consistency, in the docs we seem to do this for all interactive elements

atomiks · 2025-07-07T09:10:58Z

The main issue with disabling text selection is that you can't copy the name of the prop when trying to select it. Double clicking also allows the entire text to be selected. Maybe trying to click on text shouldn't open it, but everywhere else is fine

colmtuite · 2025-07-22T06:27:12Z

@mj12albert I mentioned setting scroll-margin-top to 0 on the meeting, but didn't understand the reasoning or outcome. Isn't this better?

Screen.Recording.2025-07-22.at.07.25.47.mov

mj12albert · 2025-07-22T14:42:24Z

@mj12albert I mentioned setting scroll-margin-top to 0 on the meeting, but didn't understand the reasoning or outcome. Isn't this better?

I updated it to 0, what about in the mobile layout do you want the scroll margin to make the trigger flush against the header? @colmtuite

colmtuite · 2025-07-22T17:41:09Z

@mj12albert yea, looks nice 👌

mj12albert · 2025-07-23T13:14:57Z

For aligning the mobile layout of the various tables, the triggers all use display: flex by default (the base Accordion styles) unless there's 3 or more "cells" then it'll change to grid

Also added the overscroll graphic to the trigger as it could overflow in some cases:

scrollable.mov

Any further feedback or is it good to go? @colmtuite

mj12albert added the docs Improvements or additions to the documentation. label Jun 18, 2025

mj12albert force-pushed the docs/disclosure-props-table branch 2 times, most recently from ee2882d to c06723b Compare June 18, 2025 15:30

romgrk reviewed Jun 18, 2025

View reviewed changes

docs/src/components/Accordion.tsx Outdated Show resolved Hide resolved

romgrk reviewed Jun 18, 2025

View reviewed changes

mj12albert mentioned this pull request Jun 18, 2025

[accordion] <summary> / <details> based implementation #1148

Open

mj12albert force-pushed the docs/disclosure-props-table branch 4 times, most recently from d40518c to 0f4851e Compare June 24, 2025 18:16

romgrk reviewed Jun 24, 2025

View reviewed changes

mj12albert force-pushed the docs/disclosure-props-table branch 2 times, most recently from 015c0ac to b0fdd83 Compare June 27, 2025 17:34

mj12albert force-pushed the docs/disclosure-props-table branch 5 times, most recently from bd4384c to b20172b Compare July 3, 2025 09:04

mj12albert changed the title ~~[docs] Native details-summary props table~~ [docs] New props table Jul 7, 2025

mj12albert force-pushed the docs/disclosure-props-table branch from 66b69cf to 8433206 Compare July 7, 2025 08:54

mj12albert force-pushed the docs/disclosure-props-table branch from 8433206 to 07d4cde Compare July 7, 2025 17:44

mj12albert added 12 commits July 21, 2025 12:35

Fix prop default colors

157cb18

Detailed type tooltip

5b164a1

Fix styles

a4cbd4d

Fix alignment

d649736

Fix alignment again

e5805f6

Fix mobile layout

fe83e84

Bump TableCellInner min height to match accordion

b9e7ce6

Show tooltip for Union

c79ecf5

Tweak styles

b420d00

Fix code block margins

6197246

Increase tooltip max width

ff646df

Link to individual props

af8e1dc

mj12albert force-pushed the docs/disclosure-props-table branch from 69c9a8f to af8e1dc Compare July 21, 2025 04:36

Fix import

43cf2dd

mj12albert added 2 commits July 22, 2025 22:26

Fix styles

43b096c

Update scroll margin

20e4136

mj12albert added 2 commits July 23, 2025 19:03

Handle overflowing content in summary element

7795433

Prop name overflow

b5e635a

Fix gap

9e8ca4d

colmtuite approved these changes Jul 25, 2025

View reviewed changes

Merge branch 'master' into docs/disclosure-props-table

5457b8c

atomiks merged commit d2e2a85 into mui:master Jul 28, 2025
19 of 20 checks passed

atomiks pushed a commit to atomiks/base-ui that referenced this pull request Aug 1, 2025

[docs] New props table (mui#2135)

84ace98

mj12albert deleted the docs/disclosure-props-table branch August 4, 2025 03:51

oliviertassinari mentioned this pull request Sep 10, 2025

[docs-infra] Fix a11y and HTML errors on baseline docs page #2718

Open

atomiks pushed a commit to atomiks/base-ui that referenced this pull request Sep 10, 2025

[docs] New props table (mui#2135)

d923e6e

Uh oh!

[docs] New props table #2135

[docs] New props table #2135

Uh oh!

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Bundle size report

Uh oh!

netlify bot commented Jun 18, 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!

Uh oh!

romgrk Jun 18, 2025

Choose a reason for hiding this comment

Uh oh!

mj12albert Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

michaldudak Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

romgrk Jun 24, 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!

colmtuite Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

romgrk Jul 22, 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!

romgrk Jun 24, 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!

colmtuite Jul 22, 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!

romgrk Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

romgrk Jun 24, 2025

Choose a reason for hiding this comment

Uh oh!

mj12albert Jun 30, 2025

Choose a reason for hiding this comment

Uh oh!

mj12albert commented Jun 30, 2025

Uh oh!

atomiks commented Jul 3, 2025

Uh oh!

mj12albert commented Jul 7, 2025

Uh oh!

atomiks commented Jul 7, 2025

Uh oh!

colmtuite commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mj12albert commented Jul 22, 2025

Uh oh!

colmtuite commented Jul 22, 2025

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

mj12albert commented Jun 18, 2025 •

edited

Loading

pkg-pr-new bot commented Jun 18, 2025 •

edited

Loading

mui-bot commented Jun 18, 2025 •

edited

Loading

netlify bot commented Jun 18, 2025 •

edited

Loading

romgrk Jun 24, 2025 •

edited

Loading

romgrk Jul 22, 2025 •

edited

Loading

romgrk Jun 24, 2025 •

edited

Loading

colmtuite Jul 22, 2025 •

edited

Loading

colmtuite commented Jul 22, 2025 •

edited

Loading

mj12albert commented Jul 23, 2025 •

edited

Loading