[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.09KB^(+0.42%)	🔺+757B^(+0.53%)
@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 e8632a1

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 ~

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

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…?

siriwatknp

Review comment on type prop handling.

siriwatknp · 2026-03-20T08:42:15Z

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

      onTouchStart={handleTouchStart}
      ref={handleRef}
-      tabIndex={disabled ? -1 : tabIndex}
      type={type}


type={type} is set here as a direct JSX prop, and then buttonProps (from getButtonProps) is spread below — which also includes a resolved type (e.g. type="button" when nativeButton && !hasFormAction, or undefined otherwise).

Since the spread comes after, buttonProps.type will override the direct type={type} prop. This means the direct prop here is effectively dead code for non-link paths.

However, it also means the raw type prop (possibly undefined) does NOT take effect — the hook's resolved value always wins. Is that intentional?

If so, consider removing the direct type={type} to avoid confusion. If the intent is for the user's type to win, it should come after the spread.

Removed in 0e5501b

For buttons the hook will set the type; for links, we add it to linkProps directly

…ase-hook

# Conflicts: # packages/mui-material/src/Tab/Tab.test.js

silviuaavram

some comments, looks good! 🎉

packages/mui-material/src/Button/Button.test.js

silviuaavram · 2026-03-26T09:42:27Z

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

+
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    React.useEffect(() => {


what's wrong with adding the check inside the hook and avoid the rules-of-hooks error?

We do this everywhere, e.g. https://github.com/mui/material-ui/blob/master/packages/mui-material/src/Tooltip/Tooltip.js#L365-L372

I believe it's for bundlers to tree shake the entire effect to minimize bundle size

silviuaavram · 2026-03-26T09:45:58Z

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

+
+  const rootRef = React.useRef<HTMLElement | null>(null);
+  const focusableWhenDisabled = focusableWhenDisabledParam === true;
+  const { props: focusableWhenDisabledProps } = useFocusableWhenDisabled({


why not just return focusableWhenDisabledProps instead of wrapping into another object?

Flattened, originally was just in case we needed to return some non-props stuff

packages/mui-material/src/utils/useFocusableWhenDisabled.ts

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

silviuaavram · 2026-03-26T09:59:02Z

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

+
+  const getButtonProps = React.useCallback(
+    <ExternalProps extends ButtonBaseExternalProps = ButtonBaseExternalProps>(
+      externalProps = EMPTY as ExternalProps,


In other cases I see we also default with {} instead of this EMPTY

A micro-optimization to avoid creating the empty object more than once, it could be worthwhile to do a sweep through the whole lib to fix this

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

siriwatknp reviewed Mar 18, 2026

View reviewed changes

packages/mui-material/src/ButtonBase/ButtonBase.js Outdated Show resolved Hide resolved

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

Merge branch 'master' into refactor/button-base-hook

126eb4a

siriwatknp reviewed Mar 20, 2026

View reviewed changes

fix button type attribute

0e5501b

mj12albert requested a review from siriwatknp March 20, 2026 15:19

Merge remote-tracking branch 'upstream/master' into refactor/button-b…

03064c9

…ase-hook

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

Merge remote-tracking branch 'upstream/master' into button-base-hook

84cd8b4

# Conflicts: # packages/mui-material/src/Tab/Tab.test.js

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

mj12albert added 2 commits March 26, 2026 03:31

Merge branch 'master' into button-base-hook

9262ff4

fixes

72ee9ea

siriwatknp approved these changes Mar 26, 2026

View reviewed changes

silviuaavram approved these changes Mar 26, 2026

View reviewed changes

mj12albert added 4 commits March 26, 2026 22:07

fixes

98316b3

add a test

64f23b4

flatten hook return val

6d3ed9a

Merge branch 'master' into refactor/button-base-hook

e8632a1

mj12albert enabled auto-merge (squash) March 26, 2026 15:06

mj12albert merged commit da873f0 into mui:master Mar 26, 2026
23 checks passed

mj12albert deleted the refactor/button-base-hook branch March 26, 2026 15:19

This was referenced Mar 30, 2026

[chip] Add ChipButton, ChipLink and ChipDelete #48015

Open

[button][button base] Document type attribute #48146

Open

[Button][Checkbox] Allow receiving focus when disabled #32917

Open


		#### 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!

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!

siriwatknp left a comment

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!

silviuaavram left a comment

Choose a reason for hiding this comment

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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 Mar 18, 2026 •

edited

Loading