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.

RadioGroup

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>

Para demonstrar os botões horizontalmente, defina a propriedade row: <RadioGroup row />.

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

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: Material-UI 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 (Void [opcional]): Callback disparado quando um botão de opção é selecionado.
  • 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.
<RadioButton
  value="radioA"
  inputProps={{ 'aria-label': 'Radio A' }}
/>

API