Selection Controls

Selection Controls allow users to complete tasks that involve making choices, or switching settings on or off.

Selection controls are found on screens that ask users to make decisions or declare preferences such as settings or dialogs.

Three types of selection controls are covered in this section:

Radio Buttons allow the selection of a single option from a set.
Checkboxes allow the selection of multiple options from a set.
Switches allow a selection to be turned on or off.

Accessibility

All form controls should have a label to identify it, this includes radio buttons, checkboxes, and switches. In most cases, this is done by using the <label> element (FormControlLabel).

When a label can't be used, it's necessary to add an attribute directly to the input component. In this case, you can apply the additional attribute (e.g. aria-label, aria-labelledby, title) via the inputProps property.

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

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

Radio Buttons

Radio buttons allow the user to select one option from a set. Use radio buttons when the user needs to see all available options. If available options can be collapsed, consider using a drop-down menu because it uses less space.

Radio buttons should have the most commonly used option selected by default.

RadioGroup is a helpful wrapper used to group Radio components that provides an easier API, and proper keyboard accessibility to the group.

() => {
  const [value, setValue] = React.useState('female');

  const handleChange = (e) => {
    setValue(e.target.value);
  };

  return (
    <div>
      <FormControl component="fieldset">
        <FormLabel component="legend">Gender</FormLabel>
        <RadioGroup name="gender1" value={value} onChange={handleChange}>
          <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="(Disabled option)"
          />
        </RadioGroup>
      </FormControl>
    </div>
  );
};

() => {
  const [value, setValue] = React.useState('female');

  const handleChange = (e) => {
    setValue(e.target.value);
  };

  return (
    <div>
      <FormControl component="fieldset">
        <FormLabel component="legend">Gender</FormLabel>
        <RadioGroup name="gender1" value={value} onChange={handleChange}>
          <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="(Disabled option)"
          />
        </RadioGroup>
      </FormControl>
    </div>
  );
};

Checkboxes

Checkboxes give users the ability to input a choice between options and may be used:

When the setting applied by the user should be confirmed and reviewed before the selection is applied.
When multiple options are available and one or more options can be selected.
To provide a better experience when selecting related items from a list.
To give a clear distinction between the selected and unselected states.
When there is a list of related items to select from.
A single yes/no choice is provided.

() => {
  const [checked, setChecked] = React.useState(true);

  const handleChange = (e) => {
    setChecked(e.target.checked);
  };

  return (
    <FormGroup>
      <FormControlLabel
        control={<Checkbox checked={checked} onChange={handleChange} value="checked" />}
        label="Checked"
      />
      <FormControlLabel control={<Checkbox value="unchecked" />} label="Unchecked" />
      <FormControlLabel disabled control={<Checkbox value="disabled" />} label="Disabled" />
      <FormControlLabel
        disabled
        control={<Checkbox checked value="disabledChecked" />}
        label="Disabled Checked"
      />
      <FormControlLabel
        control={
          <Checkbox icon={<FavoriteBorder />} checkedIcon={<Favorite />} value="checkedCustom" />
        }
        label="Custom icon"
      />
    </FormGroup>
  );
};

() => {
  const [checked, setChecked] = React.useState(true);

  const handleChange = (e) => {
    setChecked(e.target.checked);
  };

  return (
    <FormGroup>
      <FormControlLabel
        control={<Checkbox checked={checked} onChange={handleChange} value="checked" />}
        label="Checked"
      />
      <FormControlLabel control={<Checkbox value="unchecked" />} label="Unchecked" />
      <FormControlLabel disabled control={<Checkbox value="disabled" />} label="Disabled" />
      <FormControlLabel
        disabled
        control={<Checkbox checked value="disabledChecked" />}
        label="Disabled Checked"
      />
      <FormControlLabel
        control={
          <Checkbox icon={<FavoriteBorder />} checkedIcon={<Favorite />} value="checkedCustom" />
        }
        label="Custom icon"
      />
    </FormGroup>
  );
};

Checkboxes with FormGroup

FormGroup is a helpful wrapper used to group selection controls components that provides an easier API.

() => {
  const [checked, setChecked] = React.useState({ gilad: true, jason: true, antoine: false });
  const [error, setError] = React.useState(false);

  React.useEffect(() => {
    // Trigger error if more or less than 2 checked
    const hasError = Object.values(checked).filter((i) => i).length !== 2;
    setError(hasError);
  }, [checked]);

  const handleChange = (e, name) => {
    setChecked({ ...checked, [name]: e.target.checked });
  };

  return (
    <Grid container spacing={3}>
      <Grid item lg={6}>
        <FormControl component="fieldset">
          <FormLabel component="legend">Assign responsibility</FormLabel>
          <FormGroup>
            <FormControlLabel
              control={
                <Checkbox
                  checked={checked['gilad']}
                  onChange={(e) => handleChange(e, 'gilad')}
                  value="gilad"
                />
              }
              label="Gilad Gray"
            />
            <FormControlLabel
              control={
                <Checkbox
                  checked={checked['jason']}
                  onChange={(e) => handleChange(e, 'jason')}
                  value="jason"
                />
              }
              label="Jason Killian"
            />
            <FormControlLabel
              control={
                <Checkbox
                  checked={checked['antoine']}
                  onChange={(e) => handleChange(e, 'antoine')}
                  value="antoine"
                />
              }
              label="Antoine Llorca"
            />
          </FormGroup>
          <FormHelperText>Be careful</FormHelperText>
        </FormControl>
      </Grid>
      <Grid item lg={6}>
        <FormControl required error={error} component="fieldset">
          <FormLabel component="legend">Pick two</FormLabel>
          <FormGroup>
            <FormControlLabel
              control={
                <Checkbox
                  checked={checked['gilad']}
                  onChange={(e) => handleChange(e, 'gilad')}
                  value="gilad"
                />
              }
              label="Gilad Gray"
            />
            <FormControlLabel
              control={
                <Checkbox
                  checked={checked['jason']}
                  onChange={(e) => handleChange(e, 'jason')}
                  value="jason"
                />
              }
              label="Jason Killian"
            />
            <FormControlLabel
              control={
                <Checkbox
                  checked={checked['antoine']}
                  onChange={(e) => handleChange(e, 'antoine')}
                  value="antoine"
                />
              }
              label="Antoine Llorca"
            />
          </FormGroup>
          <FormHelperText>You can display an error</FormHelperText>
        </FormControl>
      </Grid>
    </Grid>
  );
};

() => {
  const [checked, setChecked] = React.useState({ gilad: true, jason: true, antoine: false });
  const [error, setError] = React.useState(false);

  React.useEffect(() => {
    // Trigger error if more or less than 2 checked
    const hasError = Object.values(checked).filter((i) => i).length !== 2;
    setError(hasError);
  }, [checked]);

  const handleChange = (e, name) => {
    setChecked({ ...checked, [name]: e.target.checked });
  };

  return (
    <Grid container spacing={3}>
      <Grid item lg={6}>
        <FormControl component="fieldset">
          <FormLabel component="legend">Assign responsibility</FormLabel>
          <FormGroup>
            <FormControlLabel
              control={
                <Checkbox
                  checked={checked['gilad']}
                  onChange={(e) => handleChange(e, 'gilad')}
                  value="gilad"
                />
              }
              label="Gilad Gray"
            />
            <FormControlLabel
              control={
                <Checkbox
                  checked={checked['jason']}
                  onChange={(e) => handleChange(e, 'jason')}
                  value="jason"
                />
              }
              label="Jason Killian"
            />
            <FormControlLabel
              control={
                <Checkbox
                  checked={checked['antoine']}
                  onChange={(e) => handleChange(e, 'antoine')}
                  value="antoine"
                />
              }
              label="Antoine Llorca"
            />
          </FormGroup>
          <FormHelperText>Be careful</FormHelperText>
        </FormControl>
      </Grid>
      <Grid item lg={6}>
        <FormControl required error={error} component="fieldset">
          <FormLabel component="legend">Pick two</FormLabel>
          <FormGroup>
            <FormControlLabel
              control={
                <Checkbox
                  checked={checked['gilad']}
                  onChange={(e) => handleChange(e, 'gilad')}
                  value="gilad"
                />
              }
              label="Gilad Gray"
            />
            <FormControlLabel
              control={
                <Checkbox
                  checked={checked['jason']}
                  onChange={(e) => handleChange(e, 'jason')}
                  value="jason"
                />
              }
              label="Jason Killian"
            />
            <FormControlLabel
              control={
                <Checkbox
                  checked={checked['antoine']}
                  onChange={(e) => handleChange(e, 'antoine')}
                  value="antoine"
                />
              }
              label="Antoine Llorca"
            />
          </FormGroup>
          <FormHelperText>You can display an error</FormHelperText>
        </FormControl>
      </Grid>
    </Grid>
  );
};

Switches

Switches give users the ability to input a choice between states and may be used when:

There is no need for further action to apply the selection choice.
If a user is toggling between independent selections.
A setting requires an on/off or show/hide function to display the results.
Selections do not need a review or confirmation.

The option that the switch controls, as well as the state it’s in, should be made clear from the corresponding inline label, added via the FormControlLabel component.

() => {
  const [checked, setChecked] = React.useState(true);

  const handleChange = (e) => {
    setChecked(e.target.checked);
  };

  return (
    <FormGroup>
      <FormControlLabel
        control={<Switch checked={checked} onChange={handleChange} value="checked" />}
        label="On (checked)"
      />
      <FormControlLabel control={<Switch value="unchecked" />} label="Off (checked)" />
      <FormControlLabel disabled control={<Switch value="disabled" />} label="Disabled Off" />
      <FormControlLabel
        disabled
        control={<Switch checked value="disabledChecked" />}
        label="Disabled On"
      />
    </FormGroup>
  );
};

() => {
  const [checked, setChecked] = React.useState(true);

  const handleChange = (e) => {
    setChecked(e.target.checked);
  };

  return (
    <FormGroup>
      <FormControlLabel
        control={<Switch checked={checked} onChange={handleChange} value="checked" />}
        label="On (checked)"
      />
      <FormControlLabel control={<Switch value="unchecked" />} label="Off (checked)" />
      <FormControlLabel disabled control={<Switch value="disabled" />} label="Disabled Off" />
      <FormControlLabel
        disabled
        control={<Switch checked value="disabledChecked" />}
        label="Disabled On"
      />
    </FormGroup>
  );
};

Switches with FormGroup

FormGroup is a helpful wrapper used to group selection controls components that provides an easier API. However, we encourage you to use a Checkbox instead.

() => {
  const [checked, setChecked] = React.useState({ gilad: true, jason: true, antoine: false });

  const handleChange = (e, name) => {
    setChecked({ ...checked, [name]: e.target.checked });
  };

  return (
    <FormControl component="fieldset">
      <FormLabel component="legend">Assign responsibility</FormLabel>
      <FormGroup row>
        <FormControlLabel
          control={
            <Switch
              checked={checked['gilad']}
              onChange={(e) => handleChange(e, 'gilad')}
              value="gilad"
            />
          }
          label="Gilad Gray"
        />
        <FormControlLabel
          control={
            <Switch
              checked={checked['jason']}
              onChange={(e) => handleChange(e, 'jason')}
              value="jason"
            />
          }
          label="Jason Killian"
        />
        <FormControlLabel
          control={
            <Switch
              checked={checked['antoine']}
              onChange={(e) => handleChange(e, 'antoine')}
              value="antoine"
            />
          }
          label="Antoine Llorca"
        />
      </FormGroup>
      <FormHelperText>Be careful</FormHelperText>
    </FormControl>
  );
};

() => {
  const [checked, setChecked] = React.useState({ gilad: true, jason: true, antoine: false });

  const handleChange = (e, name) => {
    setChecked({ ...checked, [name]: e.target.checked });
  };

  return (
    <FormControl component="fieldset">
      <FormLabel component="legend">Assign responsibility</FormLabel>
      <FormGroup row>
        <FormControlLabel
          control={
            <Switch
              checked={checked['gilad']}
              onChange={(e) => handleChange(e, 'gilad')}
              value="gilad"
            />
          }
          label="Gilad Gray"
        />
        <FormControlLabel
          control={
            <Switch
              checked={checked['jason']}
              onChange={(e) => handleChange(e, 'jason')}
              value="jason"
            />
          }
          label="Jason Killian"
        />
        <FormControlLabel
          control={
            <Switch
              checked={checked['antoine']}
              onChange={(e) => handleChange(e, 'antoine')}
              value="antoine"
            />
          }
          label="Antoine Llorca"
        />
      </FormGroup>
      <FormHelperText>Be careful</FormHelperText>
    </FormControl>
  );
};

Selection Controls

Accessibility

Radio Buttons

Checkboxes

Checkboxes with FormGroup

Switches

Switches with FormGroup

Properties

<Radio />

<RadioGroup />

<Checkbox />

<Switch />

<FormControl />

<FormLabel />

<FormControlLabel />

<FormGroup />