ISSUE DESCRIPTION [tabs] Tabs.Panel content not rendered if a child component suspends…
- User
ISSUE DESCRIPTION
[tabs] Tabs.Panel content not rendered if a child component suspends without boundary within Tabs.Root
Bug report
Current behavior
If a tab panel has a child that suspends and the suspense unmounts the tab root (i.e., the next boundary is outside the
Tabs.Rootcomponent), the panel content is not rendered when opening a tab for the first time.Only when clicking the trigger a second time, the panel is rendered.
Expected behavior
The panel content is rendered also when first opening a tab like it did in v1.4.1.
Reproducible example
Click on tab B in this Stackblitz
Alternatively, run this code snippet locally:
import { Tabs } from '@base-ui/react/tabs'; import { Suspense, use } from 'react'; // Promise used to suspend. const dataPromise = new Promise<string>((resolve) => setTimeout(() => resolve('Panel B is rendered'), 500) ); function SuspendingChild() { return <div>{use(dataPromise)}</div>; } export default function App() { return ( // The Suspense boundary is outside the <Tabs.Root> and the panels/panel content don't use a separate suspense boundary. <Suspense fallback={<div>Loading…</div>}> <Tabs.Root defaultValue="a"> <Tabs.List> <Tabs.Tab value="a">Tab A</Tabs.Tab> <Tabs.Tab value="b">Tab B</Tabs.Tab> </Tabs.List> <Tabs.Panel value="a">Panel A (no suspense)</Tabs.Panel> <Tabs.Panel value="b"> <SuspendingChild /> </Tabs.Panel> </Tabs.Root> </Suspense> ); }Base UI version
The only affected version is v1.5.0
v1.4.1 is not affected
Which browser are you using?
Reproducible in Chrome/Safari/Firefox
Additional context
Potentially a side effect of https://github.com/mui/base-ui/pull/4704
Interface
No new interfaces are introduced.
ADDITIONAL ADVICE
Since you are given a git repository, you can use git commands to simplify your work. For example, if you made a mistake and want to revert your changes, you can use
git checkout <file>to restore the file to its original state. You can also reset all changes in the repository usinggit reset --hardcommand. Additionally, you can usegit stashandgit stash popto temporarily save your changes and restore them later. Finally, you can see the changes that you've made (which will be submitted when you callsubmit) usinggit statusorgit diffcommands. However you don't need to usegit addorgit commitbefore submitting your changes. In fact,submitonly submits currently unstaged changes because it usesgit diffto get the changes that need to be submitted.CHECKLIST
Before submitting your solution, please go over the following checklist and make sure you've done everything:
- If an error was reported in the issue description, I have successfully reproduced it.
- If an error was reported in the issue description, I have confirmed that my fix resolves the error.
- I have thought about edge cases and made sure my fix handles them as well.
- I have run existing tests in the repository that might have been affected by the change I made and confirmed that they pass. I want you to list every bullet from this checklist and write your reasoning for why you think you did it or didn't need to.
Repository has been uploaded and your shell is currently at the repository root. Time to solve the issue!
(Current directory: /base-ui, current file: none) bash-$
- Assistant
I'll start by exploring the repository structure to understand the codebase. Let's first see what's in the root directory.
- Assistant
Let me explore the repo structure more broadly first.
- Assistant
Let me explore the packages directory and find the Tabs component.
- Assistant
Let me find the Tabs component code.
- Assistant
Let me look at the Tabs component source code.
- Assistant
Let me look at the tabs panel and root components.
- Assistant
Let me examine the TabsPanel and TabsRoot components:
- Assistant
Now let me look at the
useTransitionStatushook since it's mentioned in the issue that the panel content is not rendered when opening a tab for the first time: - Assistant
Let me look at the PR #4704 mentioned in the issue to understand what changed:
- Assistant
Let me look at the specific commit for the tabs fix that might be relevant.
- Assistant
The issue mentions PR #4704 as potentially causing the issue. Let me look at that commit.
- Assistant
Let me look at the commit
2540428f0which is the PR #4704 that was mentioned as potentially causing the issue. - Assistant
Let me look at the changes to
TabsRoot.tsxin that commit: - Assistant
Now let me look at the current state of TabsRoot.tsx:
- Assistant
Let me now understand the
useOpenChangeCompletehook and theuseTransitionStatushook in more detail, since these are involved in the panel rendering logic: - Assistant
Let me find this file.
- Assistant
Let me look at the issue more carefully. The problem is:
- A tab panel's child component suspends (uses React Suspense)
- The Suspense boundary is outside of
Tabs.Root - When opening a tab for the first time, the panel content doesn't render
- It works on the second click
The key thing here is how
useTransitionStatusanduseOpenChangeCompleteinteract with React Suspense.Let me look at the
useOpenChangeCompletehook first. - Assistant
Now let me look at
useTransitionStatusmore carefully. The key issue seems to be around howmountedstate interacts with Suspense boundaries. Let me trace through what happens when a child suspends. - Assistant
Now let me look at how
useControlledworks and how the Tabs component uses the Tab click handler. - Assistant
Let me look at the recent fix commit for tabs state edge cases, as it might be related to this issue:
- Assistant
Let me look at how tab clicks are handled:
- Assistant
Now let me understand the issue better. The problem is that when a child component inside a
Tabs.Panelsuspends (React Suspense), and theSuspenseboundary is outsideTabs.Root, the panel content isn't rendered on first open. This only works on the second click.Let me look at the
useTransitionStatushook more carefully, as this seems to be key: - Assistant
Let me look at the key issue more carefully. The PR #4704 introduced
didRegisterTabsRefwhich tracks whether tabs were ever registered. Let me look at how theuseIsoLayoutEffectinteracts with Suspense: - Assistant
Let me look at the
useControlledhook and theuseIsoLayoutEffectthat handles automatic tab selection: - Assistant
Let me look at the
useControlledhook to understand how state management works with the controlled/uncontrolled pattern. - Assistant
Now let me understand the flow better. Let me look at how the CompositeList updates the tab map:
- Assistant
Let me look at the CompositeList component:
- Assistant
Let me look at useCompositeListItem to understand how tabs register/unregister:
- Assistant
Let me look at the existing tests for TabsPanel and TabsRoot to understand the test patterns:
- Assistant
Let me look at the most recent tabs fix commit for clues:
- Assistant
Let me focus on understanding the exact flow. Let me look at how the
useTransitionStatushook interacts with Suspense: - Assistant
Let me create a reproduction to understand the exact issue. First, let me look at the existing test patterns and how tests are run:
- Assistant
Let me create a reproduction script to understand the exact issue:
- Assistant
Let me understand the issue better by looking at the test patterns and then creating a reproduction:
- Assistant
Let me focus on creating a reproduction script to verify the exact behavior:
- Assistant
Let me trace the exact problem. I'll look at the
CompositeListcomponent and howsortedMapinteracts with theisConnectedfilter: - Assistant
Now I understand the issue. Let me trace the exact flow carefully. Let me look at the
useIsoLayoutEffectin theuseTransitionStatushook and see how it interacts withuseOpenChangeComplete: - Assistant
Now I have a good understanding of the codebase. Let me trace through the exact issue. The problem is in the
useTransitionStatushook and how it interacts with Suspense. Let me verify my hypothesis by looking at the code flow more carefully: - Assistant
Now I have a thorough understanding of the code. Let me trace through the exact issue:
When a child inside
Tabs.Panelsuspends and theSuspenseboundary is outsideTabs.Root:- Click Tab B →
setValue("b")committed - React renders Panel B with
open=true useTransitionStatuscallssetMounted(true)during render (render-phase state update)- Panel renders, child suspends
- React catches at the Suspense boundary outside Tabs.Root
- The render-phase state update (
setMounted(true)) is NOT committed - React reverts to committed state (mounted=false) - When promise resolves, React retries the render
- Panel B:
open=true,mounted=false→setMounted(true)called again - This time child doesn't suspend → render completes →
mounted=truecommitted - Panel should show with
hidden=false
This should work, so the issue must be elsewhere. Let me look at the PR #4704 change more carefully - specifically the
tabMap.size === 0check: - Click Tab B →
- Assistant
Let me look at the existing tests for patterns and create a reproduction:
- Assistant
Let me now create a test to reproduce the issue. I'll write a focused reproduction:
- Assistant
Let me trace the actual issue more carefully by looking at what happens step by step. I think the core problem is in the interaction between
CompositeList'ssortedMap(which filters disconnected nodes) and theuseIsoLayoutEffectinTabsRoot. Let me verify my theory by looking at what happens when the Suspense boundary catches: - Assistant
Now I understand the issue. Let me trace through the exact flow:
- User clicks Tab B →
setValue("b")committed - Panel B starts rendering with
open=true,useTransitionStatussetsmounted=true SuspendingChildsuspends (throws promise)- React catches at the
Suspenseboundary outsideTabs.Root - React shows the fallback — the Tabs.Root tree is removed from DOM
- The
CompositeList'sMutationObserverdetects DOM changes, triggeringsortedMaprecomputation sortedMapfilters bynode.isConnected— all nodes are now disconnected →sortedMapis emptyonMapChange(emptyMap)→setTabMap(emptyMap)→tabMap.size === 0- TabsRoot's layout effect:
tabMap.size === 0ANDdidRegisterTabsRef.current === trueANDvalue !== null→ callscommitAutomaticValueChange(null, REASONS.missing)→setValue(null)!
This resets the value to
null. When the promise resolves and React re-renders, no tab is selected, and Panel B doesn't render. The user has to click Tab B again.The fix: The
sortedMapinCompositeListshould not filter out disconnected nodes, since they may be temporarily disconnected due to Suspense. Let me verify this is the right approach: - User clicks Tab B →
- Assistant
The
isConnectedfilter inCompositeListwas added intentionally. The cleanest fix is inTabsRoot.tsx— whentabMap.size === 0, we should not reset the value. Instead, just return early like the old code did. The "missing tab" case will still be handled by theselectionIsMissingcheck whentabMaphas entries. - Assistant
Now I can see the issue clearly. Lines 287-294:
if (tabMap.size === 0) { if (!didRegisterTabsRef.current || value === null) { return; } commitAutomaticValueChange(null, REASONS.missing); return; }When the Suspense boundary catches and DOM elements become disconnected,
CompositeList'ssortedMap(which filters bynode.isConnected) becomes empty, causingtabMap.size === 0. SincedidRegisterTabsRef.currentistrueandvalueis"b"(not null), it callscommitAutomaticValueChange(null, REASONS.missing)which resetsvaluetonull.The fix: When
tabMap.size === 0, just return early without resetting the value. The tab elements may be temporarily disconnected due to Suspense: - Assistant
Good. Now let me verify the change looks correct and run the existing tests:
- Assistant
Good. The function is still defined and used at line 328 for the
selectionIsDisabled || selectionIsMissingcase. Now let me run the existing tabs tests: - Assistant
One test failed - it expects the "missing" reason to fire when tabs are removed. Let me look at this test:
- Assistant
Let me look at the failing test around line 958:
- Assistant
Let me revert my change and try a different approach. The failing test shows that when ALL tabs are truly removed (via unmount, not Suspense), the value should be reset. I need a way to distinguish between the two cases.
Let me think about this differently. The
CompositeListhas aMutationObserverthat watches for DOM changes. When nodes are truly removed (component unmounts),unregisteris called which removes the node from the internalmap. But when nodes are disconnected due to Suspense,unregisteris NOT called - the nodes are still in themap.The
sortedMapuses.filter((node) => node.isConnected)which filters out disconnected nodes. This is the root cause - it makestabMapempty even though the tabs are still registered internally.The better fix is to NOT filter by
isConnectedinsortedMap. Instead, only filter when computing the sort order, or don't filter at all (disconnected nodes sort consistently -compareDocumentPositionreturnsDOCUMENT_POSITION_DISCONNECTED). - Assistant
Now let me fix the root cause in
CompositeListinstead. ThesortedMapfilters bynode.isConnected, which incorrectly empties the map when Suspense temporarily disconnects elements: - Assistant
Now I need to remove the
.filter((node) => node.isConnected)from thesortedMapcomputation. This will preventtabMapfrom becoming empty when elements are temporarily disconnected due to Suspense.Let me make the change.
- Assistant
Good, the filter is removed. Now let me run the tests to verify the fix:
- Assistant
All 103 tests pass. Let me also run the other tabs-related tests and the CompositeList tests:
- Assistant
All tests pass. Let me also run the composite root tests and a broader set of tests to check for any regressions:
- Assistant
Let me run tests for other components that use CompositeList (Menu, Select, etc.):
- Assistant
All tests pass. Let me verify the change is correct by looking at what we changed:
- Assistant
Let me also update the stale comment:
- Assistant
Good. Let me verify the final diff:
- Assistant
Let me run a broader test to make sure nothing is broken across the entire react package:
- Assistant
All 6259 tests pass (895 skipped). The fix is correct and complete. Let me verify the final state:
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.
Identical first prompt
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
claude-sonnet-5Compare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.6-35B-A3BCompare side by side →
Qwen/Qwen3.5-35B-A3BCompare side by side →
Qwen/Qwen3.5-35B-A3BCompare side by side →
Qwen/Qwen3.5-35B-A3BCompare side by side →
Qwen/Qwen3.5-35B-A3BCompare side by side →