--- productId: material-ui title: React Checkbox component components: Checkbox, FormControl, FormGroup, FormLabel, FormControlLabel materialDesign: https://m2.material.io/components/selection-controls#checkboxes githubLabel: 'scope: checkbox' waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/ githubSource: packages/mui-material/src/Checkbox --- # Checkbox Checkboxes allow the user to select one or more items from a set. Checkboxes can be used to turn an option on or off. If you have multiple options appearing in a list, you can preserve space by using checkboxes instead of on/off switches. If you have a single option, avoid using a checkbox and use an on/off switch instead. ## Basic checkboxes ```tsx import Checkbox from '@mui/material/Checkbox'; const label = { slotProps: { input: { 'aria-label': 'Checkbox demo' } } }; export default function Checkboxes() { return (
); } ``` ## Label You can provide a label to the `Checkbox` thanks to the `FormControlLabel` component. ```tsx import FormGroup from '@mui/material/FormGroup'; import FormControlLabel from '@mui/material/FormControlLabel'; import Checkbox from '@mui/material/Checkbox'; export default function CheckboxLabels() { return ( } label="Label" /> } label="Required" /> } label="Disabled" /> ); } ``` ## Size Use the `size` prop or customize the font size of the svg icons to change the size of the checkboxes. ```tsx import Checkbox from '@mui/material/Checkbox'; const label = { slotProps: { input: { 'aria-label': 'Checkbox demo' } } }; export default function SizeCheckboxes() { return (
); } ``` ## Color ```tsx import { pink } from '@mui/material/colors'; import Checkbox from '@mui/material/Checkbox'; const label = { slotProps: { input: { 'aria-label': 'Checkbox demo' } } }; export default function ColorCheckboxes() { return (
); } ``` ## Icon ```tsx import Checkbox from '@mui/material/Checkbox'; import FavoriteBorder from '@mui/icons-material/FavoriteBorder'; import Favorite from '@mui/icons-material/Favorite'; import BookmarkBorderIcon from '@mui/icons-material/BookmarkBorder'; import BookmarkIcon from '@mui/icons-material/Bookmark'; const label = { slotProps: { input: { 'aria-label': 'Checkbox demo' } } }; export default function IconCheckboxes() { return (
} checkedIcon={} /> } checkedIcon={} />
); } ``` ## Controlled You can control the checkbox with the `checked` and `onChange` props: ```tsx import * as React from 'react'; import Checkbox from '@mui/material/Checkbox'; export default function ControlledCheckbox() { const [checked, setChecked] = React.useState(true); const handleChange = (event: React.ChangeEvent) => { setChecked(event.target.checked); }; return ( ); } ``` ## Indeterminate A checkbox input can only have two states in a form: checked or unchecked. It either submits its value or doesn't. Visually, there are **three** states a checkbox can be in: checked, unchecked, or indeterminate. You can change the indeterminate icon using the `indeterminateIcon` prop. ```tsx import * as React from 'react'; import Box from '@mui/material/Box'; import Checkbox from '@mui/material/Checkbox'; import FormControlLabel from '@mui/material/FormControlLabel'; export default function IndeterminateCheckbox() { const [checked, setChecked] = React.useState([true, false]); const handleChange1 = (event: React.ChangeEvent) => { setChecked([event.target.checked, event.target.checked]); }; const handleChange2 = (event: React.ChangeEvent) => { setChecked([event.target.checked, checked[1]]); }; const handleChange3 = (event: React.ChangeEvent) => { setChecked([checked[0], event.target.checked]); }; const children = ( } /> } /> ); return (
} /> {children}
); } ``` :::warning When indeterminate is set, the value of the `checked` prop only impacts the form submitted values. It has no accessibility or UX implications. ::: ## FormGroup `FormGroup` is a helpful wrapper used to group selection control components. ```tsx import * as React from 'react'; import Box from '@mui/material/Box'; import FormLabel from '@mui/material/FormLabel'; import FormControl from '@mui/material/FormControl'; import FormGroup from '@mui/material/FormGroup'; import FormControlLabel from '@mui/material/FormControlLabel'; import FormHelperText from '@mui/material/FormHelperText'; import Checkbox from '@mui/material/Checkbox'; export default function CheckboxesGroup() { const [state, setState] = React.useState({ gilad: true, jason: false, antoine: false, }); const handleChange = (event: React.ChangeEvent) => { setState({ ...state, [event.target.name]: event.target.checked, }); }; const { gilad, jason, antoine } = state; const error = [gilad, jason, antoine].filter((v) => v).length !== 2; return ( Assign responsibility } label="Gilad Gray" /> } label="Jason Killian" /> } label="Antoine Llorca" /> Be careful Pick two } label="Gilad Gray" /> } label="Jason Killian" /> } label="Antoine Llorca" /> You can display an error ); } ``` ## Label placement You can change the placement of the label: ```tsx import Checkbox from '@mui/material/Checkbox'; import FormGroup from '@mui/material/FormGroup'; import FormControlLabel from '@mui/material/FormControlLabel'; import FormControl from '@mui/material/FormControl'; import FormLabel from '@mui/material/FormLabel'; export default function FormControlLabelPosition() { return ( Label placement } label="Bottom" labelPlacement="bottom" /> } label="End" labelPlacement="end" /> ); } ``` ## 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 { styled } from '@mui/material/styles'; import Checkbox, { CheckboxProps } from '@mui/material/Checkbox'; const BpIcon = styled('span')(({ theme }) => ({ borderRadius: 3, width: 16, height: 16, boxShadow: 'inset 0 0 0 1px rgba(16,22,26,.2), inset 0 -1px 0 rgba(16,22,26,.1)', backgroundColor: '#f5f8fa', backgroundImage: 'linear-gradient(180deg,hsla(0,0%,100%,.8),hsla(0,0%,100%,0))', '.Mui-focusVisible &': { outline: '2px auto rgba(19,124,189,.6)', outlineOffset: 2, }, 'input:hover ~ &': { backgroundColor: '#ebf1f5', ...theme.applyStyles('dark', { backgroundColor: '#30404d', }), }, 'input:disabled ~ &': { boxShadow: 'none', background: 'rgba(206,217,224,.5)', ...theme.applyStyles('dark', { background: 'rgba(57,75,89,.5)', }), }, ...theme.applyStyles('dark', { boxShadow: '0 0 0 1px rgb(16 22 26 / 40%)', backgroundColor: '#394b59', backgroundImage: 'linear-gradient(180deg,hsla(0,0%,100%,.05),hsla(0,0%,100%,0))', }), })); const BpCheckedIcon = styled(BpIcon)({ backgroundColor: '#137cbd', backgroundImage: 'linear-gradient(180deg,hsla(0,0%,100%,.1),hsla(0,0%,100%,0))', '&::before': { display: 'block', width: 16, height: 16, backgroundImage: "url(\"data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath" + " fill-rule='evenodd' clip-rule='evenodd' d='M12 5c-.28 0-.53.11-.71.29L7 9.59l-2.29-2.3a1.003 " + "1.003 0 00-1.42 1.42l3 3c.18.18.43.29.71.29s.53-.11.71-.29l5-5A1.003 1.003 0 0012 5z' fill='%23fff'/%3E%3C/svg%3E\")", content: '""', }, 'input:hover ~ &': { backgroundColor: '#106ba3', }, }); // Inspired by blueprintjs function BpCheckbox(props: CheckboxProps) { return ( } icon={} slotProps={{ input: { 'aria-label': 'Checkbox demo' } }} {...props} /> ); } export default function CustomizedCheckbox() { return (
); } ``` 🎨 If you are looking for inspiration, you can check [MUI Treasury's customization examples](https://mui-treasury.com/primitive/checkbox). ## When to use - [Checkboxes vs. Radio Buttons](https://www.nngroup.com/articles/checkboxes-vs-radio-buttons/) - [Checkboxes vs. Switches](https://uxplanet.org/checkbox-vs-toggle-switch-7fc6e83f10b8) ## Accessibility (WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) - All form controls should have labels, and this includes radio buttons, checkboxes, and switches. In most cases, this is done by using the `