[ButtonBase] Add `nativeButton` prop by mj12albert · Pull Request #47989 · mui/material-ui

mj12albert · 2026-03-16T07:53:17Z

Currently this JSX

const CustomButton = React.forwardRef<HTMLButtonElement>(function CustomButton(
  props,
  ref
) {
  return <button ref={ref} {...props} />;
});

<Button component={CustomButton} disabled>
  Custom
</Button>

Renders this incorrect HTML: https://stackblitz.com/edit/7wy4fcg4?file=src%2FDemo.tsx

<button tabindex="-1" role="button" aria-disabled="true">Custom</button>

Continuing from #47985, the component === 'button' heuristic doesn't work for when component is a React component; an explicit nativeButton: boolean prop is required upfront to render the correct HTML, with the constraint that the attributes have to be resolved before mount (so there is no DOM to check)

Who is affected and how:

A dev warning will be shown to users who are either:

replacing a native button with a component that resolves to a non-<button> element (e.g. component={MySpan}), or
replacing a non-native button (e.g. a div) with a component that resolves to a <button> element

e.g.

✅ Button component={CustomButton} -> no warning if it resolves to <button>
⚠️ Button component={StyledSpan} -> warn unless nativeButton={false} is specified
✅ MenuItem component={CustomLi} -> no warning if it doesn't resolve to <button>
⚠️ MenuItem component={CustomButton} -> warn unless nativeButton={true}

Affected components:

Button, Fab, IconButton, ListItemButton, MenuItem, StepButton, Tab, ToggleButton, AccordionSummary, BottomNavigationAction, CardActionArea, TableSortLabel inherit the nativeButton prop via ButtonBase
PaginationItem doesn't use ExtendButtonBaseTypeMap for some reason so the type/proptype needed to be manually added
Chip conditionally forwards nativeButton depending on whether it's a link (backward compatibility with "legacy" mode)

Preview

Added a docs section in the Button page: https://deploy-preview-47989--material-ui.netlify.app/material-ui/react-button/#rendering-non-native-buttons

mui-bot · 2026-03-16T07:54:09Z

Netlify deploy preview

Bundle size report

Bundle	Parsed size	Gzip size
@mui/material	🔺+2.1KB^(+0.41%)	🔺+711B^(+0.49%)
@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 de25a79

siriwatknp · 2026-03-16T09:35:36Z

I am good with the new prop but we should have a clear example (ideally real scenario) to update the docs too.

mj12albert · 2026-03-17T21:16:30Z

packages/mui-material/src/ButtonBase/useButtonBase.ts

+        if (disabled) {
+          event.preventDefault();
+          return;
+        }


@siriwatknp Following up on the comment in #47985 (comment)

The additional click guard + return here would only affect anybody counting on programmatically focusing and clicking a disabled non-native ButtonBase-based component then also expecting the click handler to run, similar to #48003

mj12albert · 2026-03-17T22:15:07Z

I am good with the new prop but we should have a clear example (ideally real scenario) to update the docs too.

Added a brief section here ~

mj12albert · 2026-03-18T04:58:52Z

packages/mui-material/src/ButtonBase/useButtonBase.ts

+  /**
+   * An additional function that will run before the user's `onKeyDown`, e.g.
+   * to trigger the ripple effect in `<ButtonBase>`.
+   */
+  onBeforeKeyDown?: React.KeyboardEventHandler<any> | undefined;
+  /**
+   * An additional function that will run before the user's `onKeyDown`, e.g.
+   * to control the ripple effect in `<ButtonBase>`.
+   */
+  onBeforeKeyUp?: React.KeyboardEventHandler<any> | undefined;


These custom onBeforeKeyX handlers are a bit odd, but it's solely for controlling the ripple

mj12albert · 2026-03-18T05:02:22Z

packages/mui-material/src/ButtonBase/ButtonBase.js

-      tabIndex={disabled ? -1 : tabIndex}
      type={type}
-      {...buttonProps}
+      {...(isLink ? linkProps : buttonProps)}


<ButtonBase> needs to allow links for compatibility reasons, but the useButtonBase hook does not and only covers button/button-likes

mj12albert · 2026-03-18T05:12:19Z

For the upgrade guide, it would be tidier and less noisy to document all of this under ### ButtonBase instead of adding a h3 for every single affected component – preview link

What do you think? @siriwatknp @silviuaavram

siriwatknp · 2026-03-18T10:41:36Z

packages/mui-material/src/ButtonBase/ButtonBase.js

+    // replaces internal handling in Chip, other components can opt-in individually to use this in the future
+    focusableWhenDisabled,
+    // private prop to allow native vs non-native button props to be resolved before mount
+    defaultNativeButton: defaultNativeButtonProp,


Better to name it as internalNativeButton. I use "internal" in MUI X too.

Updated in 04ddead

silviuaavram · 2026-03-18T12:27:57Z

docs/data/material/migration/upgrade-to-v9/upgrade-to-v9.md

+
+#### Replacing native button elements with non-interactive elements
+
+The `nativeButton` prop is available on `<ButtonBase>` and all button-like components to ensure that they are rendered with the correct HTML attributes before hydration, for example during server-side rendering. This should be specified when when passing a React component to the `component` prop of a button-like component. This should be specified if the custom component either replaces the default rendered element:


we can improve this phrasing, there's a double "when" and last 2 sentences start in the same way.

Updated in de25a79

silviuaavram · 2026-03-18T12:30:04Z

docs/data/material/components/buttons/buttons.md


+## Rendering non-native buttons
+
+The `nativeButton` prop can be used to allow buttons to remain keyboard accessible when passing a React component to the [`component`](/material-ui/guides/composition/#passing-other-react-components) prop that renders a non-interactive element like a `<div>`.


For this, this information was not enough to understand fully what's going on. Maybe we need to have another example with the other case, when nativeButton is true and custom component is actually a button. Also, a an example when the prop is true and custom component returns not a button, we mention the warning.

Maybe we need to have another example with the other case, when nativeButton is true and custom component is actually a button.

I think this is pretty rare in practice (e.g. making a MenuItem render a <button> elem) and not worth documenting, the dev warning should be self explanatory enough ~

an example when the prop is true and custom component returns not a button

Same here, the dev warnings should be enough for the user to correct the issue without having to go to the docs; only button -> span/div is worth documenting here as it's the more common use-case among the various dev warning combinations

silviuaavram · 2026-03-18T12:32:35Z

packages/mui-material/src/ButtonBase/ButtonBase.js

      },
    }),
-    [],
+    [buttonRef],


should refs be included in deps array?

It's just to satisfy eslint and has no runtime use, because the buttonRef is returned by the hook and isn't in the local scope anymore

silviuaavram · 2026-03-18T12:37:23Z

packages/mui-material/src/ButtonBase/ButtonBase.js

   */
  LinkComponent: PropTypes.elementType,
+  /**
+   * Whether the custom component should render a native `<button>` element when


The custom component already renders whatever the user tells it to render. The nativeButton only allows non-buttons to retain button a11y. Or at least that's what I understood.

Instead of should, how about Whether the custom component is expected to render…?

mj12albert added the component: ButtonBase The React component. label Mar 16, 2026

mj12albert force-pushed the refactor/button-base-hook branch from 53c397d to 0396ac9 Compare March 16, 2026 09:02

mj12albert mentioned this pull request Mar 16, 2026

[ButtonBase] Fix native button detection #47985

Merged

1 task

zannager added the scope: button Changes related to the button. label Mar 16, 2026

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Mar 16, 2026

mj12albert force-pushed the refactor/button-base-hook branch from 51fc75b to b0f14e2 Compare March 16, 2026 14:47

github-actions bot added PR: out-of-date The pull request has merge conflicts and can't be merged. and removed PR: out-of-date The pull request has merge conflicts and can't be merged. labels Mar 16, 2026

mj12albert added 4 commits March 17, 2026 22:44

Extract a hook from ButtonBase

9f31eab

Expose nativeButton to ButtonBase consumers

b15a4cc

Refactor: assume the default element when nativeButton is omitted

875833e

docs:api

ed9507a

mj12albert force-pushed the refactor/button-base-hook branch from b0f14e2 to 2e14d7f Compare March 17, 2026 14:46

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Mar 17, 2026

mj12albert force-pushed the refactor/button-base-hook branch 4 times, most recently from f84fa2b to 6b83890 Compare March 17, 2026 16:27

Refactor

ae47aa4

mj12albert force-pushed the refactor/button-base-hook branch from 6b83890 to ae47aa4 Compare March 17, 2026 16:56

mj12albert commented Mar 17, 2026

View reviewed changes

mj12albert force-pushed the refactor/button-base-hook branch from 9dc6ca8 to 0562586 Compare March 17, 2026 21:24

add a doc

f4b40dc

mj12albert force-pushed the refactor/button-base-hook branch from 0562586 to f4b40dc Compare March 17, 2026 21:49

mj12albert added accessibility a11y type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature. and removed accessibility a11y labels Mar 18, 2026

fixes

ce75c06

mj12albert commented Mar 18, 2026

View reviewed changes

mj12albert marked this pull request as ready for review March 18, 2026 05:08

mj12albert requested review from silviuaavram and siriwatknp March 18, 2026 05:08

mj12albert changed the title ~~[ButtonBase] Extract a hook and add nativeButton prop~~ [ButtonBase] Add nativeButton prop Mar 18, 2026

Fix tests

9322548

mj12albert force-pushed the refactor/button-base-hook branch from 5bb437e to 9322548 Compare March 18, 2026 05:17

siriwatknp reviewed Mar 18, 2026

View reviewed changes

docs

0e3a9a6

mj12albert force-pushed the refactor/button-base-hook branch from be48251 to 0e3a9a6 Compare March 18, 2026 11:04

rename

04ddead

silviuaavram reviewed Mar 18, 2026

View reviewed changes

docs

de25a79

mj12albert requested review from silviuaavram and siriwatknp March 18, 2026 20:48


		#### Replacing native button elements with non-interactive elements

		The `nativeButton` prop is available on `<ButtonBase>` and all button-like components to ensure that they are rendered with the correct HTML attributes before hydration, for example during server-side rendering. This should be specified when when passing a React component to the `component` prop of a button-like component. This should be specified if the custom component either replaces the default rendered element:


		## Rendering non-native buttons

		The `nativeButton` prop can be used to allow buttons to remain keyboard accessible when passing a React component to the [`component`](/material-ui/guides/composition/#passing-other-react-components) prop that renders a non-interactive element like a `<div>`.

Uh oh!

Conversation

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

Uh oh!

Who is affected and how:

Affected components:

Preview

Uh oh!

mui-bot commented Mar 16, 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!

siriwatknp commented Mar 16, 2026

Uh oh!

mj12albert Mar 17, 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!

mj12albert commented Mar 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mj12albert Mar 18, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mj12albert commented Mar 16, 2026 •

edited

Loading

mui-bot commented Mar 16, 2026 •

edited

Loading

mj12albert Mar 17, 2026 •

edited

Loading

mj12albert commented Mar 18, 2026 •

edited

Loading

mj12albert Mar 18, 2026 •

edited

Loading