---
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 carefulPick 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 `