Botões de opção

Botões de opção permitem o usuário selecionar uma das opções de um conjunto.

Use botões de opção quando um usuário precisar ver todas as opções disponíveis. If available options can be collapsed, consider using a Select component because it uses less space.

Os botões de opção devem ter a opção comum e mais usada selecionada por padrão.

Radio group

O componente RadioGroup é um wrapper utilizado para agrupar componentes Radio, fornece uma API mais simples e adequada para a acessibilidade por teclado.

Gender

FemaleMaleOther

<FormControl>
  <FormLabel id="demo-radio-buttons-group-label">Gender</FormLabel>
  <RadioGroup
    aria-labelledby="demo-radio-buttons-group-label"
    defaultValue="female"
    name="radio-buttons-group"
  >
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
    <FormControlLabel value="other" control={<Radio />} label="Other" />
  </RadioGroup>
</FormControl>

<FormControl>
  <FormLabel id="demo-radio-buttons-group-label">Gender</FormLabel>
  <RadioGroup
    aria-labelledby="demo-radio-buttons-group-label"
    defaultValue="female"
    name="radio-buttons-group"
  >
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
    <FormControlLabel value="other" control={<Radio />} label="Other" />
  </RadioGroup>
</FormControl>

Press Enter to start editing

Direção

To lay out the buttons horizontally, set the row prop:

Gender

FemaleMaleOtherother

Controlled

You can control the radio with the value and onChange props:

Gender

FemaleMale

<FormControl>
  <FormLabel id="demo-controlled-radio-buttons-group">Gender</FormLabel>
  <RadioGroup
    aria-labelledby="demo-controlled-radio-buttons-group"
    name="controlled-radio-buttons-group"
    value={value}
    onChange={handleChange}
  >
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
  </RadioGroup>
</FormControl>

<FormControl>
  <FormLabel id="demo-controlled-radio-buttons-group">Gender</FormLabel>
  <RadioGroup
    aria-labelledby="demo-controlled-radio-buttons-group"
    name="controlled-radio-buttons-group"
    value={value}
    onChange={handleChange}
  >
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
  </RadioGroup>
</FormControl>

Press Enter to start editing

Botões de opção independentes

O componente Radio também pode ser usado de forma independente, sem o wrapper RadioGroup.

<Radio
  checked={selectedValue === 'a'}
  onChange={handleChange}
  value="a"
  name="radio-buttons"
  inputProps={{ 'aria-label': 'A' }}
/>
<Radio
  checked={selectedValue === 'b'}
  onChange={handleChange}
  value="b"
  name="radio-buttons"
  inputProps={{ 'aria-label': 'B' }}
/>

<Radio
  checked={selectedValue === 'a'}
  onChange={handleChange}
  value="a"
  name="radio-buttons"
  inputProps={{ 'aria-label': 'A' }}
/>
<Radio
  checked={selectedValue === 'b'}
  onChange={handleChange}
  value="b"
  name="radio-buttons"
  inputProps={{ 'aria-label': 'B' }}
/>

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 radios.

<Radio {...controlProps('a')} size="small" />
<Radio {...controlProps('b')} />
<Radio
  {...controlProps('c')}
  sx={{
    '& .MuiSvgIcon-root': {
      fontSize: 28,
    },
  }}
/>

<Radio {...controlProps('a')} size="small" />
<Radio {...controlProps('b')} />
<Radio
  {...controlProps('c')}
  sx={{
    '& .MuiSvgIcon-root': {
      fontSize: 28,
    },
  }}
/>

Press Enter to start editing

Cor

<Radio {...controlProps('a')} />
<Radio {...controlProps('b')} color="secondary" />
<Radio {...controlProps('c')} color="success" />
<Radio {...controlProps('d')} color="default" />
<Radio
  {...controlProps('e')}
  sx={{
    color: pink[800],
    '&.Mui-checked': {
      color: pink[600],
    },
  }}
/>

<Radio {...controlProps('a')} />
<Radio {...controlProps('b')} color="secondary" />
<Radio {...controlProps('c')} color="success" />
<Radio {...controlProps('d')} color="default" />
<Radio
  {...controlProps('e')}
  sx={{
    color: pink[800],
    '&.Mui-checked': {
      color: pink[600],
    },
  }}
/>

Press Enter to start editing

Posicionamento do rótulo

Você pode alterar o posicionamento do rótulo com o componente FormControlLabel na propriedade labelPlacement:

Label placement

TopStartBottomEnd

Exibição de erro

Em geral, os botões de opção devem ter um valor selecionado por padrão. Se esse não for o caso, você pode exibir um erro se nenhum valor estiver selecionado quando o formulário for submetido:

Opções customizadas

Aqui está um exemplo de customização do componente. You can learn more about this in the overrides documentation page.

Gender

FemaleMaleOther(Disabled option)

`useRadioGroup`

Para situações de uso avançadas de customização, um hook useRadioGroup() é exposto. Ele retorna o valor do contexto do grupo de botões de opção pai. O componente de botões de opção usa este hook internamente.

API

import { useRadioGroup } from '@material-ui/core/RadioGroup';

Retornos

value (object):

value.name (string [opcional]): O nome usado para fazer referência ao valor do controle.
value.onChange (func [optional]): Callback fired when a radio button is selected.
value.value (any [opcional]): Valor do botão de opção selecionado.

Exemplo

FirstSecond

<RadioGroup name="use-radio-group" defaultValue="first">
  <MyFormControlLabel value="first" label="First" control={<Radio />} />
  <MyFormControlLabel value="second" label="Second" control={<Radio />} />
</RadioGroup>

<RadioGroup name="use-radio-group" defaultValue="first">
  <MyFormControlLabel value="first" label="First" control={<Radio />} />
  <MyFormControlLabel value="second" label="Second" control={<Radio />} />
</RadioGroup>

Press Enter to start editing

Quando usar

Caixas de Seleção vs. Botões de Opção

Acessibilidade

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

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.

<Radio
  value="radioA"
  inputProps={{
    'aria-label': 'Radio A',
  }}
/>

API

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