Button

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

Introduction

The Button component replaces the native HTML <button> element, and offers expanded options for styling and accessibility.

Component

Usage

After installation, you can start building with this component using the following basic elements:

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

export default function MyApp() {
  return <Button>{/* button text */}</Button>;
}

Basics

The Button 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:

<CustomButton>Button</CustomButton>
<CustomButton disabled>Disabled</CustomButton>

<CustomButton>Button</CustomButton>
<CustomButton disabled>Disabled</CustomButton>

Press Enter to start editing

Anatomy

The Button component is composed of a root <button> slot with no interior slots:

<button class="BaseButton-root">
  <!-- button text goes here -->
</button>

Custom structure

Use the slots.root prop to override the root slot with a custom element:

<Button slots={{ root: 'div' }} />

If you provide a non-interactive element such as a <span>, the Button component will automatically add the necessary accessibility attributes.

Compare the attributes on the <span> in this demo with the Button from the previous demo—try inspecting them both with your browser's dev tools:

ButtonDisabled

<CustomButton slots={{ root: 'span' }}>Button</CustomButton>
<CustomButton slots={{ root: 'span' }} disabled>
  Disabled
</CustomButton>

<CustomButton slots={{ root: 'span' }}>Button</CustomButton>
<CustomButton slots={{ root: 'span' }} disabled>
  Disabled
</CustomButton>

Press Enter to start editing

Usage with TypeScript

In TypeScript, you can specify the custom component type used in the slots.root as a generic parameter of the unstyled component. This way, you can safely provide the custom root's props directly on the component:

<Button<typeof CustomComponent> slots={{ root: CustomComponent }} customProp />

The same applies for props specific to custom primitive elements:

<Button<'img'> slots={{ root: 'img' }} src="button.png" />

Hook

import useButton from '@mui/base/useButton';

The useButton hook lets you apply the functionality of a button 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.

The following demo shows how to build the same buttons as those found in the Basics section above, but with the useButton hook:

import * as React from 'react';
import clsx from 'clsx';
import { ButtonProps } from '@mui/base/Button';
import useButton from '@mui/base/useButton';
import { styled } from '@mui/system';
import Stack from '@mui/material/Stack';

const CustomButton = React.forwardRef(function CustomButton(
  props: ButtonProps,
  ref: React.ForwardedRef<any>,
) {
  const { children, disabled } = props;
  const { active, focusVisible, getRootProps } = useButton({
    ...props,
    rootRef: ref,
  });

  const classes = {
    active,
    disabled,
    focusVisible,
  };

  return (
    <CustomButtonRoot {...getRootProps()} className={clsx(classes)}>
      {children}
    </CustomButtonRoot>
  );
});

export default function UseButton() {
  return (
    <Stack spacing={2} direction="row">
      <CustomButton onClick={() => console.log('click!')}>Button</CustomButton>
      <CustomButton disabled>Disabled</CustomButton>
    </Stack>
  );
}

const blue = {
  500: '#007FFF',
  600: '#0072E5',
  700: '#0059B2',
};

const CustomButtonRoot = styled('button')`
  font-family: 'IBM Plex Sans', sans-serif;
  font-size: 0.875rem;
  line-height: 1.5;
  background-color: ${blue[500]};
  color: white;
  border-radius: 8px;
  font-weight: 600;
  padding: 8px 16px;
  cursor: pointer;
  transition: all 150ms ease;
  border: none;

  &:hover {
    background-color: ${blue[600]};
  }

  &.active {
    background-color: ${blue[700]};
  }

  &.focusVisible {
    box-shadow: 0 4px 20px 0 rgb(61 71 82 / 0.1), 0 0 0 5px rgb(0 127 255 / 0.5);
    outline: none;
  }

  &.disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }
`;

import * as React from 'react';
import clsx from 'clsx';
import { ButtonProps } from '@mui/base/Button';
import useButton from '@mui/base/useButton';
import { styled } from '@mui/system';
import Stack from '@mui/material/Stack';

const CustomButton = React.forwardRef(function CustomButton(
  props: ButtonProps,
  ref: React.ForwardedRef<any>,
) {
  const { children, disabled } = props;
  const { active, focusVisible, getRootProps } = useButton({
    ...props,
    rootRef: ref,
  });

  const classes = {
    active,
    disabled,
    focusVisible,
  };

  return (
    <CustomButtonRoot {...getRootProps()} className={clsx(classes)}>
      {children}
    </CustomButtonRoot>
  );
});

export default function UseButton() {
  return (
    <Stack spacing={2} direction="row">
      <CustomButton onClick={() => console.log('click!')}>Button</CustomButton>
      <CustomButton disabled>Disabled</CustomButton>
    </Stack>
  );
}

const blue = {
  500: '#007FFF',
  600: '#0072E5',
  700: '#0059B2',
};

const CustomButtonRoot = styled('button')`
  font-family: 'IBM Plex Sans', sans-serif;
  font-size: 0.875rem;
  line-height: 1.5;
  background-color: ${blue[500]};
  color: white;
  border-radius: 8px;
  font-weight: 600;
  padding: 8px 16px;
  cursor: pointer;
  transition: all 150ms ease;
  border: none;

  &:hover {
    background-color: ${blue[600]};
  }

  &.active {
    background-color: ${blue[700]};
  }

  &.focusVisible {
    box-shadow: 0 4px 20px 0 rgb(61 71 82 / 0.1), 0 0 0 5px rgb(0 127 255 / 0.5);
    outline: none;
  }

  &.disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }
`;

Press Enter to start editing

If you use a ref to store a reference to the button, pass it to the useButton's ref parameter, as shown in the demo above. It will get merged with a ref used internally in the hook.

Customization

Custom elements

The Button accepts a wide range of custom elements beyond HTML elements. You can even use SVGs, as the following demo illustrates:

Using with links

The following demo illustrates how to use the Button as a link, whether using the Base UI Button itself for the href, or with the Next.js Link component:

Standard link

import * as React from 'react';
import Button, { buttonClasses } from '@mui/base/Button';
import { styled } from '@mui/system';
import Stack from '@mui/material/Stack';
import Link from 'next/link';

export default function UnstyledLinkButton() {
  return (
    <Stack spacing={2} direction="row">
      <CustomButton href={'https://mui.com/'}>Standard link</CustomButton>
      <Link href={'https://mui.com/'}>
        <CustomButton>Next link</CustomButton>
      </Link>
    </Stack>
  );
}

const blue = {
  500: '#007FFF',
  600: '#0072E5',
  700: '#0059B2',
};

const grey = {
  100: '#eaeef2',
  300: '#afb8c1',
  900: '#24292f',
};

const CustomButton = styled(Button)(
  ({ theme }) => `
  font-family: IBM Plex Sans, sans-serif;
  font-weight: bold;
  font-size: 0.875rem;
  background-color: ${blue[500]};
  padding: 8px 16px;
  border-radius: 8px;
  line-height: 1.5;
  color: white;
  transition: all 150ms ease;
  cursor: pointer;
  border: none;
  box-shadow: 0px 4px 30px ${theme.palette.mode === 'dark' ? grey[900] : grey[100]};

  &:hover {
    background-color: ${blue[600]};
  }

  &.${buttonClasses.active} {
    background-color: ${blue[700]};
  }

  &.${buttonClasses.focusVisible} {
    box-shadow: 0 3px 20px 0 rgba(61, 71, 82, 0.1), 0 0 0 5px rgba(0, 127, 255, 0.5);
    outline: none;
  }
  `,
);

import * as React from 'react';
import Button, { buttonClasses } from '@mui/base/Button';
import { styled } from '@mui/system';
import Stack from '@mui/material/Stack';
import Link from 'next/link';

export default function UnstyledLinkButton() {
  return (
    <Stack spacing={2} direction="row">
      <CustomButton href={'https://mui.com/'}>Standard link</CustomButton>
      <Link href={'https://mui.com/'}>
        <CustomButton>Next link</CustomButton>
      </Link>
    </Stack>
  );
}

const blue = {
  500: '#007FFF',
  600: '#0072E5',
  700: '#0059B2',
};

const grey = {
  100: '#eaeef2',
  300: '#afb8c1',
  900: '#24292f',
};

const CustomButton = styled(Button)(
  ({ theme }) => `
  font-family: IBM Plex Sans, sans-serif;
  font-weight: bold;
  font-size: 0.875rem;
  background-color: ${blue[500]};
  padding: 8px 16px;
  border-radius: 8px;
  line-height: 1.5;
  color: white;
  transition: all 150ms ease;
  cursor: pointer;
  border: none;
  box-shadow: 0px 4px 30px ${theme.palette.mode === 'dark' ? grey[900] : grey[100]};

  &:hover {
    background-color: ${blue[600]};
  }

  &.${buttonClasses.active} {
    background-color: ${blue[700]};
  }

  &.${buttonClasses.focusVisible} {
    box-shadow: 0 3px 20px 0 rgba(61, 71, 82, 0.1), 0 0 0 5px rgba(0, 127, 255, 0.5);
    outline: none;
  }
  `,
);

Press Enter to start editing

Focus on disabled buttons

Similarly to the native HTML <button> element, the Button 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.

Base UI 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:

<CustomButton disabled>focusableWhenDisabled = false</CustomButton>
<CustomButton disabled focusableWhenDisabled>
  focusableWhenDisabled = true
</CustomButton>

<CustomButton disabled>focusableWhenDisabled = false</CustomButton>
<CustomButton disabled focusableWhenDisabled>
  focusableWhenDisabled = true
</CustomButton>

Press Enter to start editing

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.

focusableWhenDisabled = falsefocusableWhenDisabled = true

<CustomButton slots={{ root: 'span' }} disabled>
  focusableWhenDisabled = false
</CustomButton>
<CustomButton slots={{ root: 'span' }} disabled focusableWhenDisabled>
  focusableWhenDisabled = true
</CustomButton>

<CustomButton slots={{ root: 'span' }} disabled>
  focusableWhenDisabled = false
</CustomButton>
<CustomButton slots={{ root: 'span' }} disabled focusableWhenDisabled>
  focusableWhenDisabled = true
</CustomButton>

Press Enter to start editing