product | title | components | githubLabel | waiAria |
---|---|---|---|---|
base |
Unstyled React Button component and hook |
ButtonUnstyled |
component: button |
Buttons let users take actions and make choices with a single tap.
{{"component": "modules/components/ComponentLinkHeader.js", "design": false}}
ButtonUnstyled
replaces the native HTML <button>
element.
{{"demo": "UnstyledButtonIntroduction.tsx", "defaultCodeOpen": false, "bg": "gradient"}}
After installation, you can start building with this component using the following basic elements:
import ButtonUnstyled from '@mui/base/ButtonUnstyled';
export default function MyApp() {
return <ButtonUnstyled>{/* button text */}</ButtonUnstyled>;
}
ButtonUnstyled
behaves similar to the native HTML <button>
, so it wraps around the text that will be displayed on its surface.
The following demo shows how to create and style two basic buttons.
Notice that the second button cannot be clicked due to the disabled
prop:
{{"demo": "UnstyledButtonsSimple.js", "defaultCodeOpen": true}}
The ButtonUnstyled
component is composed of a root <button>
slot with no interior slots:
<button class="BaseButton-root">
<!-- button text goes here -->
</button>
:::info The following props are available on all non-utility Base components. See Usage for full details. :::
Use the component
prop to override the root slot with a custom element:
<ButtonUnstyled component="div" />
If you provide a non-interactive element such as a <span>
, the ButtonUnstyled
component will automatically add the necessary accessibility attributes.
Use the slots
prop to override any interior slots in addition to the root:
<ButtonUnstyled slots={{ root: 'div' }} />
:::warning
If the root element is customized with both the component
and slots
props, then component
will take precedence.
:::
Use the slotProps
prop to pass custom props to internal slots.
The following code snippet applies a CSS class called my-button
to the root slot:
<ButtonUnstyled slotProps={{ root: { className: 'my-button' } }} />
Compare the attributes on the <span>
in this demo with the ButtonUnstyled
from the previous demo:
{{"demo": "UnstyledButtonsSpan.js"}}
:::warning
If a ButtonUnstyled
is customized with a non-button element (i.e. <ButtonUnstyled component="span" />
), it will not submit the form it's in when clicked.
Similarly, <ButtonUnstyled component="span" type="reset">
will not reset its parent form.
:::
import { useButton } from '@mui/base/ButtonUnstyled';
The useButton
hook lets you apply the functionality of ButtonUnstyled
to a fully custom component.
It returns props to be placed on the custom component, along with fields representing the component's internal state.
Hooks do not support slot props, but they do support customization props.
:::info Hooks give you the most room for customization, but require more work to implement. With hooks, you can take full control over how your component is rendered, and define all the custom props and CSS classes you need.
You may not need to use hooks unless you find that you're limited by the customization options of their component counterparts—for instance, if your component requires significantly different structure. :::
The useButton
hook requires the ref
of the element it's used on.
The following demo shows how to build the same buttons as those found in the Basic usage section, but with the useButton
hook:
{{"demo": "UseButton.js", "defaultCodeOpen": true}}
:::info The following features can be used with both components and hooks. For the sake of simplicity, demos and code snippets primarily feature components. :::
ButtonUnstyled
accepts a wide range of custom elements beyond HTML elements.
You can even use SVGs, as the following demo illustrates:
{{"demo": "UnstyledButtonCustom.js", "defaultCodeOpen": false}}
Similarly to the native HTML <button>
element, the ButtonUnstyled
component can't receive focus when it's disabled.
This may reduce its accessibility, as screen readers won't be able to announce the existence and state of the button.
The focusableWhenDisabled
prop lets you change this behavior.
When this prop is set, the underlying button does not set the disabled
prop.
Instead, aria-disabled
is used, which makes the button focusable.
This should be used whenever the disabled button needs to be read by screen readers.
MUI Base uses this prop internally in menu items, making it possible to use the keyboard to navigate to disabled items (in compliance with ARIA guidelines).
The following demo shows how the focusableWhenDisabled
prop works—use the Tab key to navigate within this document to see that only the second button accepts the focus:
{{"demo": "UnstyledButtonsDisabledFocus.js"}}
The focusableWhenDisabled
prop works the same when the root slot is customized, except that the aria-disabled
attribute is used no regardless of the prop's state.
The ability to receive focus is controlled internally by the tabindex
attribute.
{{"demo": "UnstyledButtonsDisabledFocusCustom.js"}}