[list] Fix List sticky subheader overlapping iOS scrollbar

[sandeshdamkondwar]

Preview: https://deploy-preview-48375--material-ui.netlify.app/material-ui/react-list/

Summary

Closes #44569

On iOS, the sticky ListSubheader has zIndex: 1 which causes it to appear above the browser's overlay scrollbar indicator. Adding isolation: 'isolate' creates a new stacking context that contains the subheader's z-index, preventing it from leaking out and overlapping the scrollbar.

Per reviewer feedback, the fix is now scoped to the subheader variant (i.e. when the subheader prop is set on List) rather than applied unconditionally, so components that use List internally (e.g. Select, Menu, Autocomplete) are not affected.

Patterns covered

Pattern	Fixed?
<List subheader={<ListSubheader>...</ListSubheader>}>	✅
<List subheader={<li />}> with ListSubheader as a nested child	✅ (subheader prop is truthy)
<List><ListSubheader>...</ListSubheader></List> (no subheader prop)	❌ users can add sx={{ isolation: 'isolate' }} to List

If it's preferable to also fix the direct-child case without impacting internal usages, one option is to unconditionally apply isolation: 'isolate' since it is effectively a no-op when no sticky z-index children are present — happy to go that route if preferred.

Test plan

• Render a List with the subheader prop set to a sticky ListSubheader on iOS (or Safari with a visible scrollbar) — scrollbar should appear above the subheader
• Confirm Select, Menu, and Autocomplete dropdowns are visually unaffected

🤖 Generated with Claude Code

[code-infra-dashboard]

Deploy preview

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

Bundle size

Bundle	Parsed size	Gzip size
@mui/material	🔺+20B(0.00%)	🔺+8B(+0.01%)
@mui/lab	0B(0.00%)	0B(0.00%)
@mui/private-theming	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

---

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

[mj12albert]

Seems to fix the issue, but better to apply this only in the sticky subheader use-case and not unconditionally to the root styles since a number of other components use List internally

[sandeshdamkondwar]

Good point — moved isolation: 'isolate' into the subheader variant so it only applies when a sticky ListSubheader is in use. Updated in the latest commit.

[mj12albert]

Thanks for the PR @sandeshdamkondwar

[oliviertassinari]

I had someone look at this. I see this as an opportunity to set a target for how far we should push things. Here:

1. Let's get the "right" metadata on the issue and PR so we can run analytics on them. Added.
2. If we add code, that can break people's code, to fix a bug in a browser, we need to make sure the browser bug tracker has it. For example, so we can know when we can delete that code. Since this doesn't seem to exist already, issue created https://bugs.webkit.org/show_bug.cgi?id=313902.
3. For what I mean by "can break people's code", see this minimal demo: https://stackblitz.com/edit/vitejs-vite-r5boapd9?file=src%2FApp.tsx&terminal=dev

Screen.Recording.2026-05-02.at.19.15.21.mov

4. So, considering 3. we can't fix this bug:

https://mui.com/material-ui/react-table/#sticky-header

5. However, we can fix this one:

https://mui.com/material-ui/react-autocomplete/#grouped

6. Now, since the value proposition of a library is to go the extra mile, when teams inside organizations can't, let's get the extra mile, so: [autocomplete] Fix iOS group scrollbar overflow #48400 and [select][autocomplete] Fix iOS group scrollbar overflow base-ui#4727.

7. Actually, I'm not even sure that this fix will fly. I'm curious, let's see. We might have to revert to this solution: https://github.com/mui/base-ui/blob/e8fbc2f47c702eccbe67e15c7d746fc1fe930d60/docs/src/app/(docs)/react/components/combobox/demos/grouped/css-modules/index.module.css#L150-L151

diff --git a/packages/mui-material/src/Autocomplete/Autocomplete.js b/packages/mui-material/src/Autocomplete/Autocomplete.js
index 28f490861e..02a9a462d9 100644
--- a/packages/mui-material/src/Autocomplete/Autocomplete.js
+++ b/packages/mui-material/src/Autocomplete/Autocomplete.js
@@ -332,7 +332,6 @@ const AutocompleteListbox = styled('ul', {
     padding: '8px 0',
     maxHeight: '40vh',
     overflow: 'auto',
-    isolation: 'isolate', // Prevent overlap with iOS overlay scrollbars.
     position: 'relative',
     [`& .${autocompleteClasses.option}`]: {
       minHeight: 48,
@@ -398,6 +397,8 @@ const AutocompleteGroupLabel = styled(ListSubheader, {
   memoTheme(({ theme }) => ({
     backgroundColor: (theme.vars || theme).palette.background.paper,
     top: -8,
+    margin: '0 0.5rem 0 0',
+    width: 'calc(100% - 0.5rem)',
   })),
 );

diff --git a/packages/mui-material/src/List/List.js b/packages/mui-material/src/List/List.js
index 3e885b9208..7e09c8ae81 100644
--- a/packages/mui-material/src/List/List.js
+++ b/packages/mui-material/src/List/List.js
@@ -48,7 +48,6 @@ const ListRoot = styled('ul', {
       props: ({ ownerState }) => ownerState.subheader,
       style: {
         paddingTop: 0,
-        isolation: 'isolate', // Prevent overlap with iOS overlay scrollbars.
       },
     },
   ],
diff --git a/packages/mui-material/src/ListSubheader/ListSubheader.js b/packages/mui-material/src/ListSubheader/ListSubheader.js
index 36bd386589..596b8839c7 100644
--- a/packages/mui-material/src/ListSubheader/ListSubheader.js
+++ b/packages/mui-material/src/ListSubheader/ListSubheader.js
@@ -85,6 +85,8 @@ const ListSubheaderRoot = styled('li', {
           top: 0,
           zIndex: 1,
           backgroundColor: (theme.vars || theme).palette.background.paper,
+          margin: '0 0.5rem 0 0',
+          width: 'calc(100% - 0.5rem)',
         },
       },
     ],