SINGULARITY
DOCS
Reference
Button
Buttons enable users to perform actions and make selections with a single click.
Buttons convey actions that users can execute. They are commonly integrated into your UI in areas such as:
- Modal windows
- Forms
- Cards
- Toolbars
Basic button
The
Button component offers three variants: text (default), contained, and outlined.import * as React from 'react';
import Stack from '@mui/material/Stack';
import Button from '@mui/material/Button';
export default function BasicButtons() {
return (
<Stack spacing={2} direction="row">
<Button variant="text">Text</Button>
<Button variant="contained">Contained</Button>
<Button variant="outlined">Outlined</Button>
</Stack>
);
}Text button
Text buttonsare generally used for less prominent actions, such as those found in dialogs or cards. In cards, text buttons help keep the focus on the card's content.
import * as React from 'react';
import Button from '@mui/material/Button';
import Stack from '@mui/material/Stack';
export default function TextButtons() {
return (
<Stack direction="row" spacing={2}>
<Button>Primary</Button>
<Button disabled>Disabled</Button>
<Button href="#text-buttons">Link</Button>
</Stack>
);
}Contained button
Contained buttonsstand out with high emphasis due to their elevation and fill. They are used for primary actions within your application.
import * as React from 'react';
import Button from '@mui/material/Button';
import Stack from '@mui/material/Stack';
export default function ContainedButtons() {
return (
<Stack direction="row" spacing={2}>
<Button variant="contained">Contained</Button>
<Button variant="contained" disabled>
Disabled
</Button>
<Button variant="contained" href="#contained-buttons">
Link
</Button>
</Stack>
);
}You can eliminate the elevation effect by using the
disableElevation prop.import * as React from 'react';
import Button from '@mui/material/Button';
export default function DisableElevation() {
return (
<Button variant="contained" disableElevation>
Disable elevation
</Button>
);
}Outlined button
Outlined buttons provide medium emphasis. They are used for significant but non-primary actions in an application.
Outlined buttons serve as a lower-emphasis alternative to contained buttons or a higher-emphasis option compared to text buttons.
import * as React from 'react';
import Button from '@mui/material/Button';
import Stack from '@mui/material/Stack';
export default function OutlinedButtons() {
return (
<Stack direction="row" spacing={2}>
<Button variant="outlined">Primary</Button>
<Button variant="outlined" disabled>
Disabled
</Button>
<Button variant="outlined" href="#outlined-buttons">
Link
</Button>
</Stack>
);
}Handling clicks
All components support an
onClick handler that is attached to the root DOM element.<Button
onClick={() => {
alert('clicked');
>
Click me
</Button>Note that the documentation avoids listing native properties (of which there are many) in the components' API section.
Color
import * as React from 'react';
import Stack from '@mui/material/Stack';
import Button from '@mui/material/Button';
export default function ColorButtons() {
return (
<Stack direction="row" spacing={2}>
<Button color="secondary">Secondary</Button>
<Button variant="contained" color="success">
Success
</Button>
<Button variant="outlined" color="error">
Error
</Button>
</Stack>
);
}Besides the default button colors, you can introduce custom colors or remove unnecessary ones. Refer to the Adding new colors guide for more details.
Sizes
To adjust button sizes, utilize the
size prop for larger or smaller buttons.import * as React from 'react';
import Box from '@mui/material/Box';
import Button from '@mui/material/Button';
export default function ButtonSizes() {
return (
<Box sx={{ '& button': { m: 1 } }}>
<div>
<Button size="small">Small</Button>
<Button size="medium">Medium</Button>
<Button size="large">Large</Button>
</div>
<div>
<Button variant="outlined" size="small">
Small
</Button>
<Button variant="outlined" size="medium">
Medium
</Button>
<Button variant="outlined" size="large">
Large
</Button>
</div>
<div>
<Button variant="contained" size="small">
Small
</Button>
<Button variant="contained" size="medium">
Medium
</Button>
<Button variant="contained" size="large">
Large
</Button>
</div>
</Box>
);
}Buttons with icons and label
Incorporating icons into certain buttons can improve the user experience, as icons are often more recognizable than text alone. For instance, a delete button can be enhanced with a trash can icon.
import * as React from 'react';
import Button from '@mui/material/Button';
import DeleteIcon from '@mui/icons-material/Delete';
import SendIcon from '@mui/icons-material/Send';
import Stack from '@mui/material/Stack';
export default function IconLabelButtons() {
return (
<Stack direction="row" spacing={2}>
<Button variant="outlined" startIcon={<DeleteIcon />}>
Delete
</Button>
<Button variant="contained" endIcon={<SendIcon />}>
Send
</Button>
</Stack>
);
}Icon button
Icon buttons are frequently used in app bars and toolbars.
Icons are ideal for toggle buttons, enabling users to select or deselect an option, such as adding or removing a star from an item.
import * as React from 'react';
import IconButton from '@mui/material/IconButton';
import Stack from '@mui/material/Stack';
import DeleteIcon from '@mui/icons-material/Delete';
import AlarmIcon from '@mui/icons-material/Alarm';
import AddShoppingCartIcon from '@mui/icons-material/AddShoppingCart';
export default function IconButtons() {
return (
<Stack direction="row" spacing={1}>
<IconButton aria-label="delete">
<DeleteIcon />
</IconButton>
<IconButton aria-label="delete" disabled color="primary">
<DeleteIcon />
</IconButton>
<IconButton color="secondary" aria-label="add an alarm">
<AlarmIcon />
</IconButton>
<IconButton color="primary" aria-label="add to shopping cart">
<AddShoppingCartIcon />
</IconButton>
</Stack>
);
}Sizes
To create larger or smaller icon buttons, apply the
size prop.import * as React from 'react';
import Stack from '@mui/material/Stack';
import IconButton from '@mui/material/IconButton';
import DeleteIcon from '@mui/icons-material/Delete';
export default function IconButtonSizes() {
return (
<Stack direction="row" spacing={1} sx={{ alignItems: 'center' }}>
<IconButton aria-label="delete" size="small">
<DeleteIcon fontSize="inherit" />
</IconButton>
<IconButton aria-label="delete" size="small">
<DeleteIcon fontSize="small" />
</IconButton>
<IconButton aria-label="delete" size="large">
<DeleteIcon />
</IconButton>
<IconButton aria-label="delete" size="large">
<DeleteIcon fontSize="inherit" />
</IconButton>
</Stack>
);
}Colors
Use the
color prop to apply the theme's color palette to the component.import * as React from 'react';
import Stack from '@mui/material/Stack';
import IconButton from '@mui/material/IconButton';
import Fingerprint from '@mui/icons-material/Fingerprint';
export default function IconButtonColors() {
return (
<Stack direction="row" spacing={1}>
<IconButton aria-label="fingerprint" color="secondary">
<Fingerprint />
</IconButton>
<IconButton aria-label="fingerprint" color="success">
<Fingerprint />
</IconButton>
</Stack>
);
}Loading
From version 6.4.0, the
loading prop can be used to set icon buttons to a loading state, disabling user interactions.import * as React from 'react';
import Tooltip from '@mui/material/Tooltip';
import IconButton from '@mui/material/IconButton';
import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
export default function LoadingIconButton() {
const [loading, setLoading] = React.useState(false);
React.useEffect(() => {
const timeout = setTimeout(() => {
setLoading(false);
}, 2000);
return () => clearTimeout(timeout);
});
return (
<Tooltip title="Click to see loading">
<IconButton onClick={() => setLoading(true)} loading={loading}>
<ShoppingCartIcon />
</IconButton>
</Tooltip>
);
}Badge
The
Badge component can be used to add a badge to an IconButton.import * as React from 'react';
import { styled } from '@mui/material/styles';
import IconButton from '@mui/material/IconButton';
import Badge, { badgeClasses } from '@mui/material/Badge';
import ShoppingCartIcon from '@mui/icons-material/ShoppingCartOutlined';
const CartBadge = styled(Badge)`
& .${badgeClasses.badge} {
top: -12px;
right: -6px;
}
`;
export default function IconButtonWithBadge() {
return (
<IconButton>
<ShoppingCartIcon fontSize="small" />
<CartBadge badgeContent={2} color="primary" overlap="circular" />
</IconButton>
);
}File upload
To create a file upload button, convert the button into a label using
component="label" and include a visually hidden input with type file.import * as React from 'react';
import { styled } from '@mui/material/styles';
import Button from '@mui/material/Button';
import CloudUploadIcon from '@mui/icons-material/CloudUpload';
const VisuallyHiddenInput = styled('input')({
clip: 'rect(0 0 0 0)',
clipPath: 'inset(50%)',
height: 1,
overflow: 'hidden',
position: 'absolute',
bottom: 0,
left: 0,
whiteSpace: 'nowrap',
width: 1,
});
export default function InputFileUpload() {
return (
<Button
component="label"
role={undefined}
variant="contained"
tabIndex={-1}
startIcon={<CloudUploadIcon />}
>
Upload files
<VisuallyHiddenInput
type="file"
onChange={(event) => console.log(event.target.files)}
multiple
/>
</Button>
);
}Loading
Starting with version 6.4.0, the
loading prop allows buttons to be set to a loading state, preventing user interactions.import * as React from 'react';
import Button from '@mui/material/Button';
import SaveIcon from '@mui/icons-material/Save';
import Stack from '@mui/material/Stack';
export default function LoadingButtons() {
return (
<Stack spacing={2}>
<Stack direction="row" spacing={2}>
<Button loading variant="outlined">
Submit
</Button>
<Button loading loadingIndicator="Loading…" variant="outlined">
Fetch data
</Button>
<Button
loading
loadingPosition="start"
startIcon={<SaveIcon />}
variant="outlined"
>
Save
</Button>
</Stack>
<Button
fullWidth
loading
loadingPosition="start"
startIcon={<SaveIcon />}
variant="outlined"
>
Full width
</Button>
<Button
fullWidth
loading
loadingPosition="end"
endIcon={<SaveIcon />}
variant="outlined"
>
Full width
</Button>
<Stack direction="row" spacing={2}>
<Button loading variant="outlined" loadingPosition="start">
Submit
</Button>
<Button loading variant="outlined" loadingPosition="end">
Submit
</Button>
<Button
loading
variant="outlined"
loadingPosition="end"
startIcon={<SaveIcon />}
>
Save
</Button>
</Stack>
</Stack>
);
}Switch the loading state to observe the transition between different states.
import * as React from 'react';
import Button from '@mui/material/Button';
import Box from '@mui/material/Box';
import FormControlLabel from '@mui/material/FormControlLabel';
import Switch from '@mui/material/Switch';
import SaveIcon from '@mui/icons-material/Save';
import SendIcon from '@mui/icons-material/Send';
export default function LoadingButtonsTransition() {
const [loading, setLoading] = React.useState(true);
function handleClick() {
setLoading(true);
}
return (
<div>
<FormControlLabel
sx={{ display: 'block' }}
control={
<Switch
checked={loading}
onChange={() => setLoading(!loading)}
name="loading"
color="primary"
/>
}
label="Loading"
/>
<Box sx={{ '& > button': { m: 1 } }}>
<Button
size="small"
onClick={handleClick}
loading={loading}
variant="outlined"
disabled
>
Disabled
</Button>
<Button
size="small"
onClick={handleClick}
loading={loading}
loadingIndicator="Loading…"
variant="outlined"
>
Fetch data
</Button>
<Button
size="small"
onClick={handleClick}
endIcon={<SendIcon />}
loading={loading}
loadingPosition="end"
variant="contained"
>
Send
</Button>
<Button
size="small"
color="secondary"
onClick={handleClick}
loading={loading}
loadingPosition="start"
startIcon={<SaveIcon />}
variant="contained"
>
Save
</Button>
</Box>
<Box sx={{ '& > button': { m: 1 } }}>
<Button onClick={handleClick} loading={loading} variant="outlined" disabled>
Disabled
</Button>
<Button
onClick={handleClick}
loading={loading}
loadingIndicator="Loading…"
variant="outlined"
>
Fetch data
</Button>
<Button
onClick={handleClick}
endIcon={<SendIcon />}
loading={loading}
loadingPosition="end"
variant="contained"
>
Send
</Button>
<Button
color="secondary"
onClick={handleClick}
loading={loading}
loadingPosition="start"
startIcon={<SaveIcon />}
variant="contained"
>
Save
</Button>
</Box>
</div>
);
}:::warning When the
loading prop is set to boolean, the loading wrapper remains in the DOM to avoid a Google Translation Crash.The
loading value should always be null or boolean. Avoid the following pattern, as it may trigger the Google Translation crash:<Button {...(isFetching && { loading: true })}> :::
Customization
Below are examples of customizing the component. Learn more in the overrides documentation page.
import * as React from 'react';
import { styled } from '@mui/material/styles';
import Button, { ButtonProps } from '@mui/material/Button';
import Stack from '@mui/material/Stack';
import { purple } from '@mui/material/colors';
const BootstrapButton = styled(Button)({
boxShadow: 'none',
textTransform: 'none',
fontSize: 16,
padding: '6px 12px',
border: '1px solid',
lineHeight: 1.5,
backgroundColor: '#0063cc',
borderColor: '#0063cc',
fontFamily: [
'-apple-system',
'BlinkMacSystemFont',
'"Segoe UI"',
'Roboto',
'"Helvetica Neue"',
'Arial',
'sans-serif',
'"Apple Color Emoji"',
'"Segoe UI Emoji"',
'"Segoe UI Symbol"',
].join(','),
'&:hover': {
backgroundColor: '#0069d9',
borderColor: '#0062cc',
boxShadow: 'none',
},
'&:active': {
boxShadow: 'none',
backgroundColor: '#0062cc',
borderColor: '#005cbf',
},
'&:focus': {
boxShadow: '0 0 0 0.2rem rgba(0,123,255,.5)',
},
});
const ColorButton = styled(Button)<ButtonProps>(({ theme }) => ({
color: theme.palette.getContrastText(purple[500]),
backgroundColor: purple[500],
'&:hover': {
backgroundColor: purple[700],
},
}));
export default function CustomizedButtons() {
return (
<Stack spacing={2} direction="row">
<ColorButton variant="contained">Custom CSS</ColorButton>
<BootstrapButton variant="contained" disableRipple>
Bootstrap
</BootstrapButton>
</Stack>
);
}🎨 For inspiration, explore MUI Treasury's customization examples.
Complex button
Text Buttons, Contained Buttons, Floating Action Buttons, and Icon Buttons are all built on the
ButtonBase component. Use this foundational component to create custom interactions.import * as React from 'react';
import { styled } from '@mui/material/styles';
import Box from '@mui/material/Box';
import ButtonBase from '@mui/material/ButtonBase';
import Typography from '@mui/material/Typography';
const images = [
{
url: '/material-ui-static/images/buttons/breakfast.jpg',
title: 'Breakfast',
width: '40%',
},
{
url: '/material-ui-static/images/buttons/burgers.jpg',
title: 'Burgers',
width: '30%',
},
{
url: '/material-ui-static/images/buttons/camera.jpg',
title: 'Camera',
width: '30%',
},
];
const ImageButton = styled(ButtonBase)(({ theme }) => ({
position: 'relative',
height: 200,
[theme.breakpoints.down('sm')]: {
width: '100% !important', // Overrides inline-style
height: 100,
},
'&:hover, &.Mui-focusVisible': {
zIndex: 1,
'& .MuiImageBackdrop-root': {
opacity: 0.15,
},
'& .MuiImageMarked-root': {
opacity: 0,
},
'& .MuiTypography-root': {
border: '4px solid currentColor',
},
},
}));
const ImageSrc = styled('span')({
position: 'absolute',
left: 0,
right: 0,
top: 0,
bottom: 0,
backgroundSize: 'cover',
backgroundPosition: 'center 40%',
});
const Image = styled('span')(({ theme }) => ({
position: 'absolute',
left: 0,
right: 0,
top: 0,
bottom: 0,
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
color: theme.vars.palette.common.white,
}));
const ImageBackdrop = styled('span')(({ theme }) => ({
position: 'absolute',
left: 0,
right: 0,
top: 0,
bottom: 0,
backgroundColor: theme.vars.palette.common.black,
opacity: 0.4,
transition: theme.transitions.create('opacity'),
}));
const ImageMarked = styled('span')(({ theme }) => ({
height: 3,
width: 18,
backgroundColor: theme.vars.palette.common.white,
position: 'absolute',
bottom: -2,
left: 'calc(50% - 9px)',
transition: theme.transitions.create('opacity'),
}));
export default function ButtonBaseDemo() {
return (
<Box sx={{ display: 'flex', flexWrap: 'wrap', minWidth: 300, width: '100%' }}>
{images.map((image) => (
<ImageButton
focusRipple
key={image.title}
style={{
width: image.width,
}}
>
<ImageSrc style={{ backgroundImage: `url(${image.url})` }} />
<ImageBackdrop className="MuiImageBackdrop-root" />
<Image>
<Typography
component="span"
variant="subtitle1"
color="inherit"
sx={(theme) => ({
position: 'relative',
p: 4,
pt: 2,
pb: `calc(${theme.spacing(1)} + 6px)`,
})}
>
{image.title}
<ImageMarked className="MuiImageMarked-root" />
</Typography>
</Image>
</ImageButton>
))}
</Box>
);
}Third-party routing library
A common scenario is client-side navigation without a server request. The
ButtonBase component offers the component prop for this purpose. See a detailed guide for more information.Limitations
Cursor not-allowed
The
ButtonBase component applies pointer-events: none; to disabled buttons, which prevents the display of a disabled cursor.To use a
not-allowed cursor, you have two approaches:- CSS only. Remove the pointer-events style from the disabled state of the
<button>element:
.MuiButtonBase-root:disabled {
cursor: not-allowed;
pointer-events: auto;
}However, consider the following:
- Add
pointer-events: none;back when displaying tooltips on disabled elements. - The cursor won't change if you use an element other than a button, such as a link
<a>.
- DOM change. Wrap the button in a container:
<span style={{ cursor: 'not-allowed' }}>
<Button component={Link} disabled>
disabled
</Button>
</span>This method supports any element, such as a link
<a>.