[docs] Add @mui/base deprecation callout #45030

mj12albert · 2025-01-15T14:36:36Z

Part of #44910

Added a callout to all the /base-ui/* pages (example)
Removed the "Planned"/"Preview" chips from the sidebar
Some previously "planned" components are done in the new Base UI, the callout is just repeated in the body e.g. RadioGroup
Some planned ones are still not yet done in the new package, the body keeps the link to the related GH issue but the text is changed a bit, e.g. Drawer
I have followed (at least) the PR section of the contributing guide.

mui-bot · 2025-01-15T14:39:20Z

Netlify deploy preview

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against 64db0fa

mj12albert · 2025-01-15T14:39:45Z

docs/src/modules/components/MuiBaseDeprecation.tsx

+      <Alert severity="warning">
+        <code>@mui/base</code> has been deprecated, please use the new Base UI{' '}
+        <Link href={props.newComponentUrl}>{props.newComponentName} Component</Link> instead.
+      </Alert>
+    );
+  }
+  // console.log(props);
+  return (
+    <Alert severity="warning">
+      <code>@mui/base</code> has been deprecated, if you&apos;re looking for an unstyled React
+      component library try out <Link href="https://www.base-ui.com">Base UI</Link>
+    </Alert>


Please suggest some exact wording if this seems too short (or too blunt) @samuelsycamore @colmtuite 🙏

For this text, how about:

@mui/base has been deprecated and replaced by Base UI. We strongly advise using the newer package instead.

and for the components that have a Base UI equivalent we can say:

@mui/base has been deprecated and replaced by Base UI. Please use the Base UI {{Whatever}} component instead.

Janpot · 2025-01-15T14:47:59Z

would it make sense to also deprecate the actual @mui/base package on npm and remove it from the repository? It would be helpful to not have to keep this package's code infra up-to-date and solve edge-cases that emerge in it while the core repo evolves.

mj12albert · 2025-01-15T14:55:30Z

docs/data/base/components/radio-group/radio-group.md

@@ -3,6 +3,8 @@ productId: base-ui
 title: React Radio Group component
 githubLabel: 'component: radio'
 waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/radio/
+newUrl: https://base-ui.com/react/components/radio


For these "planned" ones, we should probably change the text in the "...isn't available yet..." callout too?

Maybe we should just remove these pages altogether (since there are no plans for them in mui/base)?

A lot of them are actually done and exist in Base UI now (RadioGroup, ToggleGroup, Tooltip), maybe we can just repeat the deprecation message

For the ones that aren't (Drawer, Rating) it could be useful to keep the link to the GH issue if it's still open and exists in the Base UI repo

samuelsycamore · 2025-01-15T18:26:40Z

docs/src/modules/components/MuiBaseDeprecation.tsx

+}) {
+  if (props.newComponentUrl && props.newComponentName) {
+    return (
+      <Alert severity="warning">


I think this warrants a big scary red callout to make sure people don't ignore it

Suggested change

<Alert severity="warning">

<Alert severity="error">

samuelsycamore · 2025-01-15T18:27:21Z

docs/src/modules/components/MuiBaseDeprecation.tsx

+  }
+  // console.log(props);
+  return (
+    <Alert severity="warning">


Suggested change

<Alert severity="warning">

<Alert severity="error">

samuelsycamore · 2025-01-15T18:35:26Z

docs/src/modules/components/MuiBaseDeprecation.tsx

+      <Alert severity="warning">
+        <code>@mui/base</code> has been deprecated, please use the new Base UI{' '}
+        <Link href={props.newComponentUrl}>{props.newComponentName} Component</Link> instead.
+      </Alert>
+    );
+  }
+  // console.log(props);
+  return (
+    <Alert severity="warning">
+      <code>@mui/base</code> has been deprecated, if you&apos;re looking for an unstyled React
+      component library try out <Link href="https://www.base-ui.com">Base UI</Link>
+    </Alert>


For this text, how about:

@mui/base has been deprecated and replaced by Base UI. We strongly advise using the newer package instead.

and for the components that have a Base UI equivalent we can say:

@mui/base has been deprecated and replaced by Base UI. Please use the Base UI {{Whatever}} component instead.

samuelsycamore · 2025-01-15T18:37:11Z

docs/data/base/components/radio-group/radio-group.md

@@ -3,6 +3,8 @@ productId: base-ui
 title: React Radio Group component
 githubLabel: 'component: radio'
 waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/radio/
+newUrl: https://base-ui.com/react/components/radio


Maybe we should just remove these pages altogether (since there are no plans for them in mui/base)?

mj12albert · 2025-01-17T14:05:27Z

would it make sense to also deprecate the actual @mui/base package on npm and remove it from the repository?

We could probably do this as soon as this callout is deployed to docs? Marking the package as deprecated on npm can probably do any time though, will discuss this next week with the team~

mj12albert · 2025-01-17T14:06:22Z

I'll open a separate PR just for the Base UI -> MUI Base text change to not clutter up the diff of this one

samuelsycamore · 2025-01-17T16:11:44Z

Tangential: does anyone else find the anchor text really hard to read here? I think there's an issue with the contrast in dark mode at least:

Edit: looks like there's two different sets of styles in play—inside and outside the body of the page:

samuelsycamore · 2025-01-17T16:08:27Z

docs/data/base/components/drawer/drawer.md

-:::warning
-The Base UI Drawer component isn't available yet, but you can upvote [this GitHub issue](https://github.com/mui/base-ui/issues/38) to see it arrive sooner.
+:::error
+@mui/base has been deprecated and has been replaced by Base UI. Please follow [this GitHub issue](https://github.com/mui/base-ui/issues/38) to track the development of the Drawer component.


copyedit nitpick: can drop the second "has been":

Suggested change

@mui/base has been deprecated and has been replaced by Base UI. Please follow [this GitHub issue](https://github.com/mui/base-ui/issues/38) to track the development of the Drawer component.

@mui/base has been deprecated and replaced by Base UI. Please follow [this GitHub issue](https://github.com/mui/base-ui/issues/38) to track the development of the Drawer component.

samuelsycamore · 2025-01-17T16:09:41Z

docs/src/components/productBaseUI/MuiBaseDeprecation.tsx

+      <Alert severity="error">
+        @mui/base has been deprecated and has been replaced by Base UI. Please use the Base UI{' '}
+        <Link href={props.newComponentUrl} color="error.800" underline="always">
+          {props.newComponentName} Component


nitpick: component doesn't need to be capitalized here

Suggested change

{props.newComponentName} Component

{props.newComponentName} component

mj12albert added the docs Improvements or additions to the documentation label Jan 15, 2025

mj12albert commented Jan 15, 2025

View reviewed changes

mj12albert force-pushed the docs/mui-base-deprecation branch from dcf6140 to b3000e9 Compare January 15, 2025 14:41

mj12albert commented Jan 15, 2025

View reviewed changes

samuelsycamore reviewed Jan 15, 2025

View reviewed changes

mj12albert added 4 commits January 17, 2025 16:51

Add deprecation message

5f31588

Add new base links to old base md

318d09b

Update text

8160426

Update incomplete component pages

edb4154

mj12albert force-pushed the docs/mui-base-deprecation branch from 6ee50a3 to edb4154 Compare January 17, 2025 08:52

prettier

64db0fa

mj12albert changed the title ~~docs/mui-base-deprecation~~ [docs] Add @mui/base deprecation callout Jan 17, 2025

mj12albert marked this pull request as ready for review January 17, 2025 14:02

mj12albert requested a review from colmtuite January 17, 2025 14:02

mj12albert requested a review from samuelsycamore January 17, 2025 14:05

samuelsycamore approved these changes Jan 17, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Add @mui/base deprecation callout #45030

[docs] Add @mui/base deprecation callout #45030

mj12albert commented Jan 15, 2025 •

edited

Loading

mui-bot commented Jan 15, 2025 •

edited

Loading

mj12albert Jan 15, 2025

samuelsycamore Jan 15, 2025 •

edited

Loading

Janpot commented Jan 15, 2025 •

edited

Loading

mj12albert Jan 15, 2025

samuelsycamore Jan 15, 2025

mj12albert Jan 16, 2025

samuelsycamore Jan 15, 2025

samuelsycamore Jan 15, 2025

samuelsycamore Jan 15, 2025 •

edited

Loading

samuelsycamore Jan 15, 2025

mj12albert commented Jan 17, 2025

mj12albert commented Jan 17, 2025

samuelsycamore commented Jan 17, 2025 •

edited

Loading

samuelsycamore Jan 17, 2025

samuelsycamore Jan 17, 2025

	@mui/base has been deprecated and has been replaced by Base UI. Please follow [this GitHub issue](https://github.com/mui/base-ui/issues/38) to track the development of the Drawer component.
	@mui/base has been deprecated and replaced by Base UI. Please follow [this GitHub issue](https://github.com/mui/base-ui/issues/38) to track the development of the Drawer component.

	{props.newComponentName} Component
	{props.newComponentName} component

[docs] Add @mui/base deprecation callout #45030

Are you sure you want to change the base?

[docs] Add @mui/base deprecation callout #45030

Conversation

mj12albert commented Jan 15, 2025 • edited Loading

mui-bot commented Jan 15, 2025 • edited Loading

Netlify deploy preview

Bundle size report

Choose a reason for hiding this comment

samuelsycamore Jan 15, 2025 • edited Loading

Choose a reason for hiding this comment

Janpot commented Jan 15, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

samuelsycamore Jan 15, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mj12albert commented Jan 17, 2025

mj12albert commented Jan 17, 2025

samuelsycamore commented Jan 17, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mj12albert commented Jan 15, 2025 •

edited

Loading

mui-bot commented Jan 15, 2025 •

edited

Loading

samuelsycamore Jan 15, 2025 •

edited

Loading

Janpot commented Jan 15, 2025 •

edited

Loading

samuelsycamore Jan 15, 2025 •

edited

Loading

samuelsycamore commented Jan 17, 2025 •

edited

Loading