[all components] Support lazy element in `render` prop #3856

oliviertassinari · 2026-01-25T00:54:29Z

Fix #2859. See #2859 (comment) for why a fix. With this PR release, we could then merge shadcn-ui/ui#9444.

You can test this work / the problem in the playground using:

import * as React from 'react';
import { Button } from "@base-ui/react/button"

// A "Fake" component to be loaded
const FakeComponent = (props) => <div style={{ color: 'red' }} {...props} />;
// A "Lazy" version that resolves after 100ms
const LazyMock = React.lazy(() => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve({ default: FakeComponent });
    }, 0);
  });
});

const AsyncServerComponent = async (props) => <div style={{ color: 'blue' }} {...props} />

export default function CloneElement() {
  return (
    <div>
      <React.Suspense fallback={<div>Loading…</div>}>
        Cases
        <Button nativeButton={false} render={<LazyMock />}>
          Lazy
        </Button>
        {/* <Button nativeButton={false} render={(props) => <LazyMock {...props} />}>
          Lazy function
        </Button> */}
        <Button nativeButton={false} render={<AsyncServerComponent />}>
          Async
        </Button>
        {/* <Button nativeButton={false} render={<React.Fragment>Bar</React.Fragment>}>
          Framgnet
        </Button> */}
        {/* <Button nativeButton={false} render={<React.Fragment><div>1</div><div>2</div></React.Fragment>}>
          Array
        </Button> */}
      </React.Suspense>
    </div>
  );
}

While I was at it, I tried to bring it to the next step. There were easy, low-hanging fruits 🍇:

Tests

I have added some missing test cases for useRenderElement().

Error recovery

I have added logic to help developers when they provide wrong values to the render prop.

Before, if you did this: <Button nativeButton={false} render={<React.Fragment>Bar</React.Fragment>}>, the error would be confusing:

now, you get something clearer. I love it 😌:

greptile-apps

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

pkg-pr-new · 2026-01-25T00:55:36Z

base-ui-tanstack-start

vite-css-base-ui-example

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

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

commit: 34e7d17

mui-bot · 2026-01-25T00:56:09Z

Bundle size report

Bundle	Parsed size	Gzip size
@base-ui/react	🔺+89B^(+0.02%)	🔺+52B^(+0.04%)

Details of bundle changes

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

netlify · 2026-01-25T00:57:35Z

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	`0e36d98`
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/697569c84e3ed1000847e0d6
😎 Deploy Preview	https://deploy-preview-3856--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.

netlify · 2026-01-25T01:00:14Z

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	`f41510f`
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/69756a6aa1b01d0008c12307
😎 Deploy Preview	https://deploy-preview-3856--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.

netlify · 2026-01-25T01:02:30Z

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	`34e7d17`
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/697753b24e3ed10008613366
😎 Deploy Preview	https://deploy-preview-3856--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.

atomiks

Nice that there's a workaround 🙌 Have some notes:

atomiks · 2026-01-25T11:01:12Z

packages/react/src/utils/useRenderElement.tsx

+          `Base UI: Expected to receive a valid React element in the "render" prop but received an invalid one.`,
+        );
+      }
+    }


Could this error message be more helpful? e.g. why is it invalid, how to fix it.

Ok, I tried to do something better, applying:

https://www.notion.so/mui-org/DevEx-Technical-writing-style-guide-7e55b517ac2e489a9ddb6d0f6dd765de?source=copy_link#85219822c3194b6f8a49ee08ea82b90a closer to the letter

and [all components][docs-infra] Update all error messages to have docs page? mui-public#222

Suggestion, add error writing style in your AGENTS.md like mui/material-ui#47668 so that review bots can suggest improvements.

packages/react/src/utils/useRenderElement.tsx

packages/react/src/utils/useRenderElement.test.tsx

Signed-off-by: atomiks <cc.glows@gmail.com>

Janpot · 2026-01-26T11:45:31Z

packages/react/src/utils/useRenderElement.tsx

+    // so we can throw before with custom message.
+    if (process.env.NODE_ENV !== 'production') {
+      if (!React.isValidElement(newElement)) {
+        throw /* minify-error-disabled */ new Error(


Why not just remove that [].join('\n')?

We don't need to minify the error, it won't run in production.

Right, but why not write error messages according to the same rules, regardless of whether there's a production guard around? And why does it matter that this error does not get minified?

Anyway, we can probably automate this check like in mui/mui-public#794

but why not write error messages according to the same rules

Fair point

why does it matter that this error does not get minified?

We still need /* minify-error-disabled */ to ignore that error.

Taking care of non-prod errors in mui/mui-public#1069

atomiks · 2026-01-26T11:54:02Z

Possibly related to this: support for a render function that returns a lazy component:

<Component render={<Lazy />} />
<Component render={(props) => <Lazy {...props} />} />

oliviertassinari · 2026-01-26T14:06:24Z

Possibly related to this: support for a render function that returns a lazy component:

@atomiks AFAIK, this already work; it doesn't go through the .cloneElement() code path. I have updated this PR's description playground, and I could see it working.

oliviertassinari requested review from atomiks and colmtuite as code owners January 25, 2026 00:54

oliviertassinari added the type: bug It doesn't behave as expected. label Jan 25, 2026

oliviertassinari requested a review from michaldudak as a code owner January 25, 2026 00:54

oliviertassinari added external dependency Blocked by external dependency, we can’t do anything about it. scope: all components Widespread work has an impact on almost all components. labels Jan 25, 2026

greptile-apps bot reviewed Jan 25, 2026

View reviewed changes

oliviertassinari mentioned this pull request Jan 25, 2026

[all components] render prop doesn't work with async components #2859

Closed

oliviertassinari force-pushed the fix-clone-element-async branch from 0e36d98 to f41510f Compare January 25, 2026 00:57

oliviertassinari force-pushed the fix-clone-element-async branch 2 times, most recently from 47b1626 to 38d0fa0 Compare January 25, 2026 00:59

oliviertassinari removed request for atomiks and colmtuite January 25, 2026 01:02

oliviertassinari force-pushed the fix-clone-element-async branch from 38d0fa0 to 3d6972e Compare January 25, 2026 01:12

This was referenced Jan 25, 2026

fix: remove unnecessary Base UI Button use client shadcn-ui/ui#9444

Open

[bug]: Base UI Button being 'use client' means you can't import buttonVariants in non-client components shadcn-ui/ui#9428

Open

[all components] Support Lazy element in render={}

49dccc7

oliviertassinari force-pushed the fix-clone-element-async branch from 3d6972e to 49dccc7 Compare January 25, 2026 01:30

atomiks reviewed Jan 25, 2026

View reviewed changes

oliviertassinari added 2 commits January 25, 2026 15:44

reduce bundle size

19c7a3d

improve a bit the error message

842ea90

oliviertassinari force-pushed the fix-clone-element-async branch from 82bcea8 to a227d2b Compare January 25, 2026 17:09

oliviertassinari added 2 commits January 25, 2026 18:18

improve error message

570f715

last piece

c5457e7

oliviertassinari force-pushed the fix-clone-element-async branch from a227d2b to c5457e7 Compare January 25, 2026 18:01

oliviertassinari mentioned this pull request Jan 25, 2026

[code-infra] Fix dection of new Error() that can't be minified mui/mui-public#1067

Open

atomiks reviewed Jan 25, 2026

View reviewed changes

packages/react/src/utils/useRenderElement.tsx Outdated Show resolved Hide resolved

atomiks reviewed Jan 26, 2026

View reviewed changes

packages/react/src/utils/useRenderElement.test.tsx Outdated Show resolved Hide resolved

Apply suggestions from code review

5250459

Signed-off-by: atomiks <cc.glows@gmail.com>

atomiks approved these changes Jan 26, 2026

View reviewed changes

atomiks added 2 commits January 26, 2026 22:36

Merge branch 'master' into fix-clone-element-async

d1639ba

Merge branch 'master' into fix-clone-element-async

34e7d17

Janpot reviewed Jan 26, 2026

View reviewed changes

atomiks changed the title ~~[all components] Support Lazy element in render={}~~ [all components] Support lazy element in render prop Jan 26, 2026

atomiks merged commit 50e164e into mui:master Jan 26, 2026
21 of 23 checks passed

oliviertassinari deleted the fix-clone-element-async branch January 26, 2026 13:54

Uh oh!

[all components] Support lazy element in render prop #3856

[all components] Support lazy element in render prop #3856

Conversation

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

Uh oh!

Tests

Error recovery

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Bundle size report

Uh oh!

netlify bot commented Jan 25, 2026

✅ Deploy Preview for base-ui ready!

Uh oh!

netlify bot commented Jan 25, 2026

✅ Deploy Preview for base-ui ready!

Uh oh!

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

Uh oh!

✅ Deploy Preview for base-ui ready!

Uh oh!

atomiks left a comment

Choose a reason for hiding this comment

Uh oh!

atomiks Jan 25, 2026

Choose a reason for hiding this comment

Uh oh!

oliviertassinari Jan 25, 2026

Choose a reason for hiding this comment

Uh oh!

Janpot Jan 26, 2026 • 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!

Uh oh!

Uh oh!

Uh oh!

Janpot Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

oliviertassinari Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

Janpot Jan 26, 2026 • 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!

oliviertassinari Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

Janpot Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

atomiks commented Jan 26, 2026

Uh oh!

oliviertassinari commented Jan 26, 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!

4 participants

[all components] Support lazy element in `render` prop #3856

[all components] Support lazy element in `render` prop #3856

oliviertassinari commented Jan 25, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 25, 2026 •

edited

Loading

mui-bot commented Jan 25, 2026 •

edited

Loading

netlify bot commented Jan 25, 2026 •

edited

Loading

Janpot Jan 26, 2026 •

edited

Loading

Janpot Jan 26, 2026 •

edited

Loading

oliviertassinari commented Jan 26, 2026 •

edited

Loading