Caixa de seleção

Caixas de seleção permitem ao usuário selecionar um ou mais itens de um conjunto.

Caixas de seleção podem ser usadas para ativar ou desativar uma opção.

Se você tem várias opções aparecendo em uma lista, você pode economizar espaço usando caixas de seleção ao invés de interruptores liga/desliga. Se você tem uma única opção, evite usar uma caixa de seleção e use um interruptor de liga/desliga.

Caixa de seleção básica

<Checkbox {...label} defaultChecked />
<Checkbox {...label} />
<Checkbox {...label} disabled />
<Checkbox {...label} disabled checked />

<Checkbox {...label} defaultChecked />
<Checkbox {...label} />
<Checkbox {...label} disabled />
<Checkbox {...label} disabled checked />

Press Enter to start editing

Caixas de seleção com FormGroup

You can provide a label to the Checkbox thanks to the FormControlLabel component.

LabelDisabled

<FormGroup>
  <FormControlLabel control={<Checkbox defaultChecked />} label="Label" />
  <FormControlLabel disabled control={<Checkbox />} label="Disabled" />
</FormGroup>

<FormGroup>
  <FormControlLabel control={<Checkbox defaultChecked />} label="Label" />
  <FormControlLabel disabled control={<Checkbox />} label="Disabled" />
</FormGroup>

Press Enter to start editing

Tamanho

Use the size prop or customize the font size of the svg icons to change the size of the checkboxes.

<Checkbox {...label} defaultChecked size="small" />
<Checkbox {...label} defaultChecked />
<Checkbox
  {...label}
  defaultChecked
  sx={{ '& .MuiSvgIcon-root': { fontSize: 28 } }}
/>

<Checkbox {...label} defaultChecked size="small" />
<Checkbox {...label} defaultChecked />
<Checkbox
  {...label}
  defaultChecked
  sx={{ '& .MuiSvgIcon-root': { fontSize: 28 } }}
/>

Press Enter to start editing

Cor

<Checkbox {...label} defaultChecked />
<Checkbox {...label} defaultChecked color="secondary" />
<Checkbox {...label} defaultChecked color="success" />
<Checkbox {...label} defaultChecked color="default" />
<Checkbox
  {...label}
  defaultChecked
  sx={{
    color: pink[800],
    '&.Mui-checked': {
      color: pink[600],
    },
  }}
/>

<Checkbox {...label} defaultChecked />
<Checkbox {...label} defaultChecked color="secondary" />
<Checkbox {...label} defaultChecked color="success" />
<Checkbox {...label} defaultChecked color="default" />
<Checkbox
  {...label}
  defaultChecked
  sx={{
    color: pink[800],
    '&.Mui-checked': {
      color: pink[600],
    },
  }}
/>

Press Enter to start editing

Ícone

<Checkbox {...label} icon={<FavoriteBorder />} checkedIcon={<Favorite />} />
<Checkbox
  {...label}
  icon={<BookmarkBorderIcon />}
  checkedIcon={<BookmarkIcon />}
/>

<Checkbox {...label} icon={<FavoriteBorder />} checkedIcon={<Favorite />} />
<Checkbox
  {...label}
  icon={<BookmarkBorderIcon />}
  checkedIcon={<BookmarkIcon />}
/>

Press Enter to start editing

Controlado

Você pode controlar a checkbox com as opções checked e onChange:

<Checkbox
  checked={checked}
  onChange={handleChange}
  inputProps={{ 'aria-label': 'controlled' }}
/>

<Checkbox
  checked={checked}
  onChange={handleChange}
  inputProps={{ 'aria-label': 'controlled' }}
/>

Press Enter to start editing

Caixa de seleção com FormControlLabel

Uma caixa de seleção só pode ter dois estados em um formulário: marcado ou desmarcado. Ou submete o seu valor ou não. Visually, there are three states a checkbox can be in: checked, unchecked, or indeterminate.

Parent

Child 1Child 2

<FormControlLabel
  label="Parent"
  control={
    <Checkbox
      checked={checked[0] && checked[1]}
      indeterminate={checked[0] !== checked[1]}
      onChange={handleChange1}
    />
  }
/>
{children}

<FormControlLabel
  label="Parent"
  control={
    <Checkbox
      checked={checked[0] && checked[1]}
      indeterminate={checked[0] !== checked[1]}
      onChange={handleChange1}
    />
  }
/>
{children}

Press Enter to start editing

Posicionamento do rótulo

FormGroup is a helpful wrapper used to group selection control components.

Posicionamento do rótulo

You can change the placement of the label:

Label placement

TopStartBottomEnd

Caixa de seleção customizada

Here is an example of customizing the component. You can learn more about this in the overrides documentation page.

<BpCheckbox />
<BpCheckbox defaultChecked />
<BpCheckbox disabled />

<BpCheckbox />
<BpCheckbox defaultChecked />
<BpCheckbox disabled />

Press Enter to start editing

🎨 If you are looking for inspiration, you can check MUI Treasury's customization examples.

Quando usar

Acessibilidade

(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)

Todos os controles de formulário devem ter rótulos, e isso inclui os botões de opção, caixas de seleção e interruptores. In most cases, this is done by using the <label> element (FormControlLabel).
Quando um rótulo não pode ser usado, é necessário adicionar um atributo diretamente no componente de entrada. Nesse caso você pode aplicar um atributo adicional (por exemplo, aria-label,aria-labelledby, title) através da propriedade inputProps.

<Checkbox value="checkedA" inputProps={{ 'aria-label': 'Checkbox A' }} />

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.