--- productId: material-ui title: Toggle Button React component components: ToggleButton, ToggleButtonGroup githubLabel: 'scope: toggle button' materialDesign: https://m2.material.io/components/buttons#toggle-button githubSource: packages/mui-material/src/ToggleButton --- # Toggle Button A Toggle Button can be used to group related options. To emphasize groups of related Toggle buttons, a group should share a common container. The `ToggleButtonGroup` controls the selected state of its child buttons when given its own `value` prop. ## Exclusive selection With exclusive selection, selecting one option deselects any other. In this example, text justification toggle buttons present options for left, center, right, and fully justified text (disabled), with only one item available for selection at a time. **Note**: Exclusive selection does not enforce that a button must be active. For that effect see [enforce value set](#enforce-value-set). ```tsx import * as React from 'react'; import FormatAlignLeftIcon from '@mui/icons-material/FormatAlignLeft'; import FormatAlignCenterIcon from '@mui/icons-material/FormatAlignCenter'; import FormatAlignRightIcon from '@mui/icons-material/FormatAlignRight'; import FormatAlignJustifyIcon from '@mui/icons-material/FormatAlignJustify'; import ToggleButton from '@mui/material/ToggleButton'; import ToggleButtonGroup from '@mui/material/ToggleButtonGroup'; export default function ToggleButtons() { const [alignment, setAlignment] = React.useState('left'); const handleAlignment = ( event: React.MouseEvent, newAlignment: string | null, ) => { setAlignment(newAlignment); }; return ( ); } ``` ## Multiple selection Multiple selection allows for logically-grouped options, like bold, italic, and underline, to have multiple options selected. ```tsx import * as React from 'react'; import FormatBoldIcon from '@mui/icons-material/FormatBold'; import FormatItalicIcon from '@mui/icons-material/FormatItalic'; import FormatUnderlinedIcon from '@mui/icons-material/FormatUnderlined'; import FormatColorFillIcon from '@mui/icons-material/FormatColorFill'; import ArrowDropDownIcon from '@mui/icons-material/ArrowDropDown'; import ToggleButton from '@mui/material/ToggleButton'; import ToggleButtonGroup from '@mui/material/ToggleButtonGroup'; export default function ToggleButtonsMultiple() { const [formats, setFormats] = React.useState(() => ['bold', 'italic']); const handleFormat = ( event: React.MouseEvent, newFormats: string[], ) => { setFormats(newFormats); }; return ( ); } ``` ## Size For larger or smaller buttons, use the `size` prop. ```tsx import * as React from 'react'; import FormatAlignLeftIcon from '@mui/icons-material/FormatAlignLeft'; import FormatAlignCenterIcon from '@mui/icons-material/FormatAlignCenter'; import FormatAlignRightIcon from '@mui/icons-material/FormatAlignRight'; import FormatAlignJustifyIcon from '@mui/icons-material/FormatAlignJustify'; import Stack from '@mui/material/Stack'; import ToggleButton from '@mui/material/ToggleButton'; import ToggleButtonGroup from '@mui/material/ToggleButtonGroup'; export default function ToggleButtonSizes() { const [alignment, setAlignment] = React.useState('left'); const handleChange = ( event: React.MouseEvent, newAlignment: string, ) => { setAlignment(newAlignment); }; const children = [ , , , , ]; const control = { value: alignment, onChange: handleChange, exclusive: true, }; return ( {children} {children} {children} ); } ``` ## Color ```tsx import * as React from 'react'; import ToggleButton from '@mui/material/ToggleButton'; import ToggleButtonGroup from '@mui/material/ToggleButtonGroup'; export default function ColorToggleButton() { const [alignment, setAlignment] = React.useState('web'); const handleChange = ( event: React.MouseEvent, newAlignment: string, ) => { setAlignment(newAlignment); }; return ( Web Android iOS ); } ``` ## Vertical buttons The buttons can be stacked vertically with the `orientation` prop set to "vertical". ```tsx import * as React from 'react'; import ViewListIcon from '@mui/icons-material/ViewList'; import ViewModuleIcon from '@mui/icons-material/ViewModule'; import ViewQuiltIcon from '@mui/icons-material/ViewQuilt'; import ToggleButton from '@mui/material/ToggleButton'; import ToggleButtonGroup from '@mui/material/ToggleButtonGroup'; export default function VerticalToggleButtons() { const [view, setView] = React.useState('list'); const handleChange = (event: React.MouseEvent, nextView: string) => { setView(nextView); }; return ( ); } ``` ## Enforce value set If you want to enforce that at least one button must be active, you can adapt your handleChange function. ```jsx const handleAlignment = (event, newAlignment) => { if (newAlignment !== null) { setAlignment(newAlignment); } }; const handleDevices = (event, newDevices) => { if (newDevices.length) { setDevices(newDevices); } }; ``` ```tsx import * as React from 'react'; import FormatAlignLeftIcon from '@mui/icons-material/FormatAlignLeft'; import FormatAlignCenterIcon from '@mui/icons-material/FormatAlignCenter'; import FormatAlignRightIcon from '@mui/icons-material/FormatAlignRight'; import LaptopIcon from '@mui/icons-material/Laptop'; import TvIcon from '@mui/icons-material/Tv'; import PhoneAndroidIcon from '@mui/icons-material/PhoneAndroid'; import Stack from '@mui/material/Stack'; import ToggleButton from '@mui/material/ToggleButton'; import ToggleButtonGroup from '@mui/material/ToggleButtonGroup'; export default function ToggleButtonNotEmpty() { const [alignment, setAlignment] = React.useState('left'); const [devices, setDevices] = React.useState(() => ['phone']); const handleAlignment = ( event: React.MouseEvent, newAlignment: string | null, ) => { if (newAlignment !== null) { setAlignment(newAlignment); } }; const handleDevices = ( event: React.MouseEvent, newDevices: string[], ) => { if (newDevices.length) { setDevices(newDevices); } }; return ( ); } ``` ## Standalone toggle button ```tsx import * as React from 'react'; import CheckIcon from '@mui/icons-material/Check'; import ToggleButton from '@mui/material/ToggleButton'; export default function StandaloneToggleButton() { const [selected, setSelected] = React.useState(false); return ( setSelected((prevSelected) => !prevSelected)} > ); } ``` ## Customization Here is an example of customizing the component. You can learn more about this in the [overrides documentation page](/material-ui/customization/how-to-customize/). ```tsx import * as React from 'react'; import { styled } from '@mui/material/styles'; import FormatAlignLeftIcon from '@mui/icons-material/FormatAlignLeft'; import FormatAlignCenterIcon from '@mui/icons-material/FormatAlignCenter'; import FormatAlignRightIcon from '@mui/icons-material/FormatAlignRight'; import FormatAlignJustifyIcon from '@mui/icons-material/FormatAlignJustify'; import FormatBoldIcon from '@mui/icons-material/FormatBold'; import FormatItalicIcon from '@mui/icons-material/FormatItalic'; import FormatUnderlinedIcon from '@mui/icons-material/FormatUnderlined'; import FormatColorFillIcon from '@mui/icons-material/FormatColorFill'; import ArrowDropDownIcon from '@mui/icons-material/ArrowDropDown'; import Divider from '@mui/material/Divider'; import Paper from '@mui/material/Paper'; import ToggleButton from '@mui/material/ToggleButton'; import ToggleButtonGroup, { toggleButtonGroupClasses, } from '@mui/material/ToggleButtonGroup'; const StyledToggleButtonGroup = styled(ToggleButtonGroup)(({ theme }) => ({ [`& .${toggleButtonGroupClasses.grouped}`]: { margin: theme.spacing(0.5), border: 0, borderRadius: theme.shape.borderRadius, [`&.${toggleButtonGroupClasses.disabled}`]: { border: 0, }, }, [`& .${toggleButtonGroupClasses.middleButton},& .${toggleButtonGroupClasses.lastButton}`]: { marginLeft: -1, borderLeft: '1px solid transparent', }, })); export default function CustomizedDividers() { const [alignment, setAlignment] = React.useState('left'); const [formats, setFormats] = React.useState(() => ['italic']); const handleFormat = ( event: React.MouseEvent, newFormats: string[], ) => { setFormats(newFormats); }; const handleAlignment = ( event: React.MouseEvent, newAlignment: string, ) => { setAlignment(newAlignment); }; return (
({ display: 'flex', border: `1px solid ${theme.palette.divider}`, flexWrap: 'wrap', })} >
); } ``` ### Spacing The demos below show how to adjust spacing between toggle buttons in horizontal and vertical orientations. #### Horizontal Spacing ```tsx import * as React from 'react'; import FormatAlignLeftIcon from '@mui/icons-material/FormatAlignLeft'; import FormatAlignCenterIcon from '@mui/icons-material/FormatAlignCenter'; import FormatAlignRightIcon from '@mui/icons-material/FormatAlignRight'; import FormatAlignJustifyIcon from '@mui/icons-material/FormatAlignJustify'; import ToggleButton, { toggleButtonClasses } from '@mui/material/ToggleButton'; import ToggleButtonGroup, { toggleButtonGroupClasses, } from '@mui/material/ToggleButtonGroup'; import { styled } from '@mui/material/styles'; const StyledToggleButtonGroup = styled(ToggleButtonGroup)(({ theme }) => ({ gap: '2rem', [`& .${toggleButtonGroupClasses.firstButton}, & .${toggleButtonGroupClasses.middleButton}`]: { borderTopRightRadius: (theme.vars || theme).shape.borderRadius, borderBottomRightRadius: (theme.vars || theme).shape.borderRadius, }, [`& .${toggleButtonGroupClasses.lastButton}, & .${toggleButtonGroupClasses.middleButton}`]: { borderTopLeftRadius: (theme.vars || theme).shape.borderRadius, borderBottomLeftRadius: (theme.vars || theme).shape.borderRadius, borderLeft: `1px solid ${(theme.vars || theme).palette.divider}`, }, [`& .${toggleButtonGroupClasses.lastButton}.${toggleButtonClasses.disabled}, & .${toggleButtonGroupClasses.middleButton}.${toggleButtonClasses.disabled}`]: { borderLeft: `1px solid ${(theme.vars || theme).palette.action.disabledBackground}`, }, })); export default function HorizontalSpacingToggleButton() { const [alignment, setAlignment] = React.useState('left'); const handleAlignment = ( event: React.MouseEvent, newAlignment: string | null, ) => { setAlignment(newAlignment); }; return ( ); } ``` #### Vertical Spacing ```tsx import * as React from 'react'; import FormatAlignLeftIcon from '@mui/icons-material/FormatAlignLeft'; import FormatAlignCenterIcon from '@mui/icons-material/FormatAlignCenter'; import FormatAlignRightIcon from '@mui/icons-material/FormatAlignRight'; import FormatAlignJustifyIcon from '@mui/icons-material/FormatAlignJustify'; import ToggleButton, { toggleButtonClasses } from '@mui/material/ToggleButton'; import ToggleButtonGroup, { toggleButtonGroupClasses, } from '@mui/material/ToggleButtonGroup'; import { styled } from '@mui/material/styles'; const StyledToggleButtonGroup = styled(ToggleButtonGroup)(({ theme }) => ({ gap: '2rem', [`& .${toggleButtonGroupClasses.firstButton}, & .${toggleButtonGroupClasses.middleButton}`]: { borderBottomRightRadius: (theme.vars || theme).shape.borderRadius, borderBottomLeftRadius: (theme.vars || theme).shape.borderRadius, }, [`& .${toggleButtonGroupClasses.lastButton}, & .${toggleButtonGroupClasses.middleButton}`]: { borderTopRightRadius: (theme.vars || theme).shape.borderRadius, borderTopLeftRadius: (theme.vars || theme).shape.borderRadius, borderTop: `1px solid ${(theme.vars || theme).palette.divider}`, }, [`& .${toggleButtonGroupClasses.lastButton}.${toggleButtonClasses.disabled}, & .${toggleButtonGroupClasses.middleButton}.${toggleButtonClasses.disabled}`]: { borderTop: `1px solid ${(theme.vars || theme).palette.action.disabledBackground}`, }, })); export default function VerticalSpacingToggleButton() { const [alignment, setAlignment] = React.useState('left'); const handleAlignment = ( event: React.MouseEvent, newAlignment: string | null, ) => { setAlignment(newAlignment); }; return ( ); } ``` ## Accessibility ### ARIA - ToggleButtonGroup has `role="group"`. You should provide an accessible label with `aria-label="label"`, `aria-labelledby="id"` or `