Pular para o conteúdo
Ajude a traduzir esta página

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. Se várias opções podem ser suprimidas da visualização, considere usar um menu suspenso (dropdown), pois ele utiliza menos espaço.

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
<FormControl component="fieldset">
  <FormLabel component="legend">Gender</FormLabel>
  <RadioGroup
    aria-label="gender"
    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>

Direção

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

Gender
<FormControl component="fieldset">
  <FormLabel component="legend">Gender</FormLabel>
  <RadioGroup row aria-label="gender" name="row-radio-buttons-group">
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
    <FormControlLabel value="other" control={<Radio />} label="Other" />
    <FormControlLabel
      value="disabled"
      disabled
      control={<Radio />}
      label="other"
    />
  </RadioGroup>
</FormControl>

Controlled

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

Gender
<FormControl component="fieldset">
  <FormLabel component="legend">Gender</FormLabel>
  <RadioGroup
    aria-label="gender"
    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>

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' }}
/>

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,
    },
  }}
/>

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],
    },
  }}
/>

Posicionamento do rótulo

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

labelPlacement

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:

Pop quiz: MUI is...

Choose wisely

Opções customizadas

Aqui está um exemplo de customização do componente. Você pode aprender mais sobre isso na página de documentação de sobrescritas.

Gender
<FormControl component="fieldset">
  <FormLabel component="legend">Gender</FormLabel>
  <RadioGroup defaultValue="female" aria-label="gender" name="customized-radios">
    <FormControlLabel value="female" control={<BpRadio />} label="Female" />
    <FormControlLabel value="male" control={<BpRadio />} label="Male" />
    <FormControlLabel value="other" control={<BpRadio />} label="Other" />
    <FormControlLabel
      value="disabled"
      disabled
      control={<BpRadio />}
      label="(Disabled option)"
    />
  </RadioGroup>
</FormControl>

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

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

Quando usar

Acessibilidade

(WAI-ARIA: https://www.w3.org/TR/wai-aria-practices/#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. Na maioria dos casos, isso é feito usando o elemento <label> (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