[docs] Wide docs layout by noraleonte · Pull Request #47950 · mui/material-ui

noraleonte · 2026-03-11T15:19:18Z

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

In this PR

Moved the Diamond sponsors to the left . This makes them independent from the ToC, which means that if the ToC is minified or hidden for smaller devices, the diamond sponsors remain visible.
Added two props to <MarkdownDocs />:
- wideLayout: increases the maximum width of the docs content to xl/1536px.
- ~~collapseToc: replaces the current ToC with a minified version on ALL breakpoints where it is visible (ToC is hidden on tablet and mobile)~~

Recording.2026-03-11.170933.mp4

The two props are independent, so technically the current ToC can be used with the wide docs or we can use the minified ToC with the narrow docs.

Open question

Do we want to change the current default behavior and enforce the minified ToC on smaller devices (at least lg and md)? Right now we hide the ToC under 1440px which might not be a great UX 🤔

…docs

mui-bot · 2026-03-11T15:20:07Z

Netlify deploy preview

https://deploy-preview-47950--material-ui.netlify.app/

Bundle size report

Bundle	Parsed size	Gzip size
@mui/material	0B^(0.00%)	0B^(0.00%)
@mui/lab	0B^(0.00%)	0B^(0.00%)
@mui/system	0B^(0.00%)	0B^(0.00%)
@mui/utils	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

Generated by 🚫 dangerJS against b24240d

mnajdova · 2026-03-11T15:38:56Z

It looks very nice 👌 Some issues I spotted:

There is some z-index issue

Table of content is missing on the other pages, e.g. https://deploy-preview-47950--material-ui.netlify.app/material-ui/react-snackbar/
Can we try making the sponsors card thinner, they look strecthed, maybe something like

mnajdova · 2026-03-11T16:02:52Z

docs/src/modules/components/MarkdownDocs.js

  const {
    disableAd = false,
    disableToc = false,
+    container,


Suggested change

container,

container = 'narrow',

?

mnajdova · 2026-03-11T16:03:15Z

docs/src/modules/components/MarkdownDocsV2.js

  const {
    disableAd = false,
    disableToc = false,
+    container,


Suggested change

container,

container = 'narrow',

Same?

mnajdova · 2026-03-11T16:13:35Z

docs/src/modules/components/AppLayoutDocs.js

    title: PropTypes.string,
  }),
  children: PropTypes.node.isRequired,
+  container: PropTypes.oneOf(['narrow', 'wide']),


I would recommend using a boolean prop if there are only two options.

dav-is · 2026-03-12T01:01:02Z

It looks perfect on my veritcal screen 😄 it's a nice touch

Nice to see it also works without JS and progressively enhances with the popover.

It looks like the feedback butons aren't full width here:

Also it seems that the entire table of contents container has cursor: click instead of just the buttons.

I'm not sure if it makes sense, but the tabindex of the table of contents comes after the content.

noraleonte · 2026-03-12T13:48:26Z

@mnajdova @dav-is Thank you for the review 🙏

fixed z-index issue
container: 'wide' | 'narrow' -> wideLayout: boolean
In the popper only the buttons have cursor:pointer
Reworked the diamond sponsors a bit to not look stratched: I kept the spacing for consistence, but places the two sponsors side by side. LMK what you think. If it still feels off we can go with changing the spacing

The default behavior of the ToC is different now: before, we were hiding the ToC entirely below xl -> Now, even if collapseToc is false, on lg we show the MiniToc instead off hiding the ToC entirely. Basically as long as we have a navigation, we have some variant of the ToC visible at all times. The ToC is hidden only on tablet and mobile now.

dav-is · 2026-03-12T13:56:03Z

Maybe we need to also show the popover on focus and change the selected item when focus changes?

Screencast.From.2026-03-12.09-53-57.webm

dav-is · 2026-03-12T14:13:06Z

Are we able to add the collapsed ToC when on other pages when the width is too small for the full ToC? I like having it on my veritcal desktop screen

noraleonte · 2026-03-12T15:05:57Z

Really good catch 🙏 Thanks
Popover now opens on focus and highlighting is working as well
MiniToC is being displayed above 900px always 😄

aarongarciah

Looking good!

I think it'd make sense to collapse the ToC only when there's not enough space. See this screenshot for example. Why hide it when there's room to display it?
The collapsed ToC accessibility is broken. The links have no label. When using a screen reader, there should be no difference between the collapsed and uncollapsed versions. See screenshots below.

The ToC popover can be treated as visual aid for sighted users (same mental model as Base UI Tooltips), so I think we could just hide it from assistive tech if the collapsed version labels are fixed.

Regular ToC

Collapsed ToC

noraleonte · 2026-03-13T13:58:56Z

Thanks for the review, Aaron 🙏

I think it'd make sense to collapse the ToC only when there's not enough space

Hmm, that could also make sense 🤔 In that case, DX question - would you
a. remove the collapseToc prop entirely and adjust the default behavior
b. change collapseToc: boolean to collapseBelow: 'ld' | 'xl' | '2xl'?

aarongarciah · 2026-03-13T14:39:48Z

Hmm, that could also make sense 🤔 In that case, DX question - would you
a. remove the collapseToc prop entirely and adjust the default behavior
b. change collapseToc: boolean to collapseBelow: 'ld' | 'xl' | '2xl'?

For context: we chatted about it and we decided to try option a

mnajdova · 2026-03-13T15:45:04Z

How will the sponsors UI look when we have third sponsor?

noraleonte · 2026-03-16T13:55:51Z

Update:

removed collapseToc prop entirely
adjusted default behavior to only render MiniToc when there isn't space for the full width one

@mnajdova an idea of what I was thinking off when I changed the sponsors layout:

Janpot · 2026-03-17T09:44:02Z

2 remarks:

I noticed the lengths of the bars follow the lengths of the strings. Would it make sense to also replicate the indentation as well, on the right side? I wonder if it would improve scannability.
hovering over one of the bars syncs with hover effect on the items in the tooltip, but not vice versa. Shouldn't hovering the text items also sync with the hover effect on the condensed view?

noraleonte · 2026-03-17T17:59:08Z

Thanks, Jan 🙏

Not sure it would for two reasons:
- The bars are pretty small so I don't think it would be visible
- They are aligned to the right wo even with indentation, they would probably look like very small bars.
  So I'm not sure it would add value 🤔
Syncing the hover of the bars with the titles felt useful because otherwise, you have no way of knowing to which section each bar would take you on click. I wasn't sure there is value in syncing the hover of the titles with the bars, since the result is expected 🤔 But it also doesn't hurt consistency so I made the change 👌

oliviertassinari · 2026-03-25T15:08:10Z

Moved the Diamond sponsors to the left

We want to support an infinite number of sponsors, but this is not going to support it. I'm also not sure about the reduced vertical space for scrolling the side nav on a 14" screen.

So how about?

We restore the previous ad placement, but simply do not show any of this when the docs mode is large. Tailwind CSS makes it work, $2M/year of donation without showing the sponsors in the docs.
We don't use the wide layout unless the component is really big, so only the scheduler today. For example, on a table page, this feels worse, It's too wide; people have to scan and read a lot more length.
We add this mode to the docs of docs-infra, meaning: https://deploy-preview-48091--material-ui.netlify.app/experiments/docs/callouts/ cc @dav-is for awareness.

Side feedback:

Are the lengths of the bars optimal?

I thought the length of a bar was supposed to encode the hx nature of them. At least, that's how Notion helps me skip h3 when I want to move to the next h2.

noraleonte added 6 commits February 23, 2026 18:40

wip

5ae2408

wip

036f3ce

adjust props

2b2b0e5

add minified ToC

15296e2

polish minified ToC

36b0e25

Merge branch 'master' of github.com:noraleonte/material-ui into wide-…

2dcfc10

…docs

noraleonte requested review from aarongarciah, dav-is, joserodolfofreitas, michelengelen, mnajdova and rita-codes March 11, 2026 15:19

noraleonte self-assigned this Mar 11, 2026

noraleonte added docs Improvements or additions to the documentation. design This is about UI or UX design, please involve a designer. type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature. labels Mar 11, 2026

noraleonte mentioned this pull request Mar 11, 2026

[docs-infra][draft] Wide docs container #46428

Closed

fix ci

390432b

mnajdova reviewed Mar 11, 2026

View reviewed changes

Marija & Connor review

4234316

noraleonte requested a review from mnajdova March 12, 2026 13:49

Connor feedback

0a69357

aarongarciah reviewed Mar 13, 2026

View reviewed changes

fix a11y

55a7151

adjust behavior

c8377c0

sync title hover with bars

b24240d

mnajdova approved these changes Mar 18, 2026

View reviewed changes

noraleonte merged commit ec3a25b into mui:master Mar 18, 2026
19 checks passed

Uh oh!

Conversation

noraleonte commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

In this PR

Open question

Uh oh!

mui-bot commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Netlify deploy preview

Bundle size report

Uh oh!

mnajdova commented Mar 11, 2026

Uh oh!

mnajdova Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

mnajdova Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

mnajdova Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

dav-is commented Mar 12, 2026

Uh oh!

noraleonte commented Mar 12, 2026

Uh oh!

dav-is commented Mar 12, 2026

Uh oh!

dav-is commented Mar 12, 2026

Uh oh!

noraleonte commented Mar 12, 2026

Uh oh!

aarongarciah left a comment

Choose a reason for hiding this comment

Uh oh!

noraleonte commented Mar 13, 2026

Uh oh!

aarongarciah commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mnajdova commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

noraleonte commented Mar 16, 2026

Uh oh!

Janpot commented Mar 17, 2026

Uh oh!

noraleonte commented Mar 17, 2026

Uh oh!

Uh oh!

oliviertassinari commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

noraleonte commented Mar 11, 2026 •

edited

Loading

mui-bot commented Mar 11, 2026 •

edited

Loading

aarongarciah commented Mar 13, 2026 •

edited

Loading

mnajdova commented Mar 13, 2026 •

edited

Loading

oliviertassinari commented Mar 25, 2026 •

edited

Loading