ChoiceGroup

When users have multiple options to choose from, it can make sense to group them together under a single heading to make it clear what is offered. A choice group gives unified instructions for a group where users can either select one (with radios) or multiple (with checkboxes) options.

Component status

Figma

Designing

Web (React)

Released

iOS (Swift)

n/a

Android (Kotlin)

n/a

Docs

Released

Content structure

Guidelines

Use for closely related options       

Choice groups override the settings of individual choices to present a coherent whole. This means they’re great for a few choices that make a single unit.

They’re not good at grouping many options, such as all countries in the world. For many options, consider using a select.

Use labels properly

Labels serve to clearly present what the choice means for users. They are especially important for people who won’t see other visual cues. But they also help everyone know exactly what to choose.

Follow the labeling advice for radios or checkboxes. In particular, make sure all the labels have a parallel structure.

Use helpful error messages

With more complicated choices, sometimes labels aren’t enough or sometimes the option the user wants isn’t available. Use clear, calm error messages when there’s a problem with a choice.

Remember that such messages are likely to invoke negative feelings, so be positive and focused on solutions to any problems.

Only messages you include for the choice group will appear. Any messages for individual choices within the group will not be shown.

import ChoiceGroup from "@kiwicom/orbit-components/lib/ChoiceGroup";
import Checkbox from "@kiwicom/orbit-components/lib/Checkbox";
import Radio from "@kiwicom/orbit-components/lib/Radio";
import Stack from "@kiwicom/orbit-components/lib/Stack";

() => {
  const [checked, setChecked] = React.useState({
    plane: false,
    train: true,
    auto: true,
  })
  const [radio, setRadio] = React.useState("non")
  return (
    <Stack>
      <ChoiceGroup
        label="Transport to search"
        error={checked.auto ? "No results for automobiles" : ""}
        onChange={(event) => {
          const { name } = event.target
          setChecked((prevState) => ({ ...prevState, [name]: !checked[name] }))
        }}
      >
        <Checkbox name="plane" label="Planes" checked={checked.plane} />
        <Checkbox name="train" label="Trains" checked={checked.train} />
        <Checkbox name="auto" label="Automobiles" checked={checked.auto} />
      </ChoiceGroup>
      <ChoiceGroup
        label="Number of stops"
        error={radio === "non" ? "No results for nonstop journeys" : ""}
        onChange={(event) => setRadio(event.target.name)}
      >
        <Radio name="non" label="Nonstop" checked={radio === "non" || false} />
        <Radio
          name="1stop"
          label="Up to 1 stop"
          checked={radio === "1stop" || false}
        />
        <Radio
          name="2stop"
          label="Up to 2 stops"
          checked={radio === "2stop" || false}
        />
      </ChoiceGroup>
    </Stack>
  )
}

Related components

Choice components

For separate choices, use the appropriate component, such as a checkbox, select, or radio.