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.

Basics

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

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

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

<Button>Button</Button>
<Button disabled>Disabled</Button>
<Button loading>Loading</Button>

<Button>Button</Button>
<Button disabled>Disabled</Button>
<Button loading>Loading</Button>

Press Enter to start editing

Disabled

Use the disabled prop to disable interaction and focus:

<Button disabled variant="solid" startDecorator={<Add />}>
  Solid
</Button>
<Button disabled color="neutral" variant="soft" startDecorator={<Add />}>
  Soft
</Button>
<Button disabled color="success" variant="outlined" startDecorator={<Add />}>
  Outlined
</Button>
<Button disabled color="danger" variant="plain" startDecorator={<Add />}>
  Plain
</Button>

<Button disabled variant="solid" startDecorator={<Add />}>
  Solid
</Button>
<Button disabled color="neutral" variant="soft" startDecorator={<Add />}>
  Soft
</Button>
<Button disabled color="success" variant="outlined" startDecorator={<Add />}>
  Outlined
</Button>
<Button disabled color="danger" variant="plain" startDecorator={<Add />}>
  Plain
</Button>

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.

<Button loading variant="solid">
  Solid
</Button>
<Button loading variant="soft">
  Soft
</Button>
<Button loading variant="outlined">
  Outlined
</Button>
<Button loading variant="plain">
  Plain
</Button>

<Button loading variant="solid">
  Solid
</Button>
<Button loading variant="soft">
  Soft
</Button>
<Button loading variant="outlined">
  Outlined
</Button>
<Button loading variant="plain">
  Plain
</Button>

Press Enter to start editing

Customization

Variants

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

<Button variant="solid">Solid</Button>
<Button variant="soft">Soft</Button>
<Button variant="outlined">Outlined</Button>
<Button variant="plain">Plain</Button>

<Button variant="solid">Solid</Button>
<Button variant="soft">Soft</Button>
<Button variant="outlined">Outlined</Button>
<Button variant="plain">Plain</Button>

Press Enter to start editing

Sizes

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

<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

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:

SolidSoftOutlinedPlain

Decorators

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

<Button startDecorator={<Add />}>Add to cart</Button>
<Button endDecorator={<KeyboardArrowRight />} color="success">
  Go to checkout
</Button>

<Button startDecorator={<Add />}>Add to cart</Button>
<Button endDecorator={<KeyboardArrowRight />} color="success">
  Go to checkout
</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:

<Button loading>Default</Button>
<Button loading loadingIndicator="Loading…">
  Custom
</Button>

<Button loading>Default</Button>
<Button loading loadingIndicator="Loading…">
  Custom
</Button>

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.

<Button loading loadingPosition="start">
  Start
</Button>
<Button loading loadingPosition="end" endDecorator={<SendIcon />}>
  End
</Button>

<Button loading loadingPosition="start">
  Start
</Button>
<Button loading loadingPosition="end" endDecorator={<SendIcon />}>
  End
</Button>

Press Enter to start editing

Link Button

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:

Open in new tab

<Button component="a" href="#as-link" startDecorator={<OpenInNew />}>
  Open in new tab
</Button>
<IconButton aria-label="Open in new tab" component="a" href="#as-link">
  <OpenInNew />
</IconButton>

<Button component="a" href="#as-link" startDecorator={<OpenInNew />}>
  Open in new tab
</Button>
<IconButton aria-label="Open in new tab" component="a" href="#as-link">
  <OpenInNew />
</IconButton>

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.

Upload a 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.

Disabled

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

--Button-gap

Icon Button

<IconButton
>
  <FavoriteBorder />
</IconButton>

CSS variables

--IconButton-size

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

Use the Base UI Button for complete ownership of the component's design, with no Material UI or Joy UI styles to override. This unstyled version of the component is the ideal choice for heavy customization with a smaller bundle size.

API

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

Button

Introduction

Playground

Basics

Disabled

Loading

Customization

Variants

Sizes

Colors

Decorators

Loading indicator

Loading position

Link Button

File upload

Icon Button

CSS variables playground

Button

Icon Button

Accessibility

Anatomy

Unstyled

API