Skip to content
+

Button

Buttons let users take actions and make choices with a single tap.

Introduction

Buttons communicate actions that users can take. The Joy UI Button component replaces the native HTML <button> element, and offers expanded options for styling and accessibility.

<Button onClick={() => {}} />

Playground


Basics

import Button from '@mui/joy/Button';

The Joy UI Button behaves similar to the native HTML <button>, so it wraps around the text that will be displayed on its surface.

The demo below shows the three basic states available to the Button: default, disabled, and loading.

Press Enter to start editing

Disabled

Use the disabled prop to disable interaction and focus:

Press Enter to start editing

Loading

Add the loading prop to show the Button's loading state. The Button is disabled as long as it's loading. See Loading indicator and Loading position for customization options.

Press Enter to start editing

Customization

Variants

The Button component supports Joy UI's four global variants: solid (default), soft, outlined, and plain.

Press Enter to start editing

Sizes

The Button component comes in three sizes: sm, md (default), and lg.

Press Enter to start editing

Colors

Every palette included in the theme is available via the color prop. Play around combining different colors with different variants.

Variant:

Decorators

Use the startDecorator and endDecorator props to append actions and icons to either side of the Button:

Press Enter to start editing

Loading indicator

The default loading indicator uses the Circular Progress component. Use the loadingIndicator prop to replace it with a custom indicator, as shown below:

Press Enter to start editing

Loading position

The loadingPosition prop sets the position of the Button's loading indicator. It supports three values:

  • center (default): The loading indicator is nested inside the loadingIndicatorCenter slot and replaces the Button's contents when in the loading state.
  • start: The loading indicator replaces the starting decorator when the Button is in the loading state.
  • end: The loading indicator replaces the ending decorator when the Button is in the loading state.
Press Enter to start editing

Buttons let users take actions, but if that action is to navigate to a new page, then an anchor tag is generally preferable over a button tag.

If you need the style of a button with the functionality of a link, then you can use the component prop to replace the default <button> with an <a>, as shown below:

Press Enter to start editing

File upload

To create a file upload button, turn the button into a label using component="label" and then create a visually-hidden input with type file.

Icon Button

import IconButton from '@mui/joy/IconButton';

Use the Icon Button component for a square button to house an icon with no text content.

CSS variables playground

Play around with the CSS variables available to the Button and Icon Button components to see how the design changes. You can use these to customize the components with both the sx prop and the theme.

Button

<Button
  startDecorator={<FavoriteBorder />}
>

CSS variables


px

Icon Button

<IconButton
>
  <FavoriteBorder />
</IconButton>

CSS variables


px

Accessibility

All Buttons must have a meaningful aria-label so their purpose can be understood by users who require assistive technology.

This is especially important for Icon Buttons because they don't contain any text. For example, an Icon Button that displays a <FavoriteBorder /> icon might have a label that looks like this:

<IconButton aria-label="Add to favorites">
  <FavoriteBorder />
</IconButton>

Anatomy

The Button component is composed of a single root <button> element that wraps around its contents:

<button class="MuiButton-root" type="button">
  <!-- Button contents -->
</button>

Unstyled

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.