Developer mode
Opens components on the React tab by default.
Your bookmarks

ListChoice

Shows one of a selectable list of items with similar structures.

When you want to present users with similar choices, it can help to make them look similar so users can quickly find the differences among them. Use list choices to present information like nearby cities at various distances from the user.

Use icons and descriptions to make the choices seem more interesting.

Component status

Figma
Released
Web (React)
Released
iOS (Swift)
n/a
Android (Kotlin)
n/a
Docs
Released

Content structure

Title: clarifies what the choice offers; checkbox: optionally indicates when the choice is selectable; icon: visually supports the choice; description: optionally adds more explanation to the choice.

Guidelines   

Use for similar structured items

List choices work well at displaying items that are similar and have the same kinds of information. For example, use them to display a list of cities to travel to.

Seeing multiple options with similar information allows users to quickly scan for what they need to know.

import InputField from "@kiwicom/orbit-components/lib/InputField";
import ListChoice from "@kiwicom/orbit-components/lib/ListChoice";
import Popover from "@kiwicom/orbit-components/lib/Popover";
() => {
  const [choice, setChoice] = React.useState("")
  return (
    <Popover
      content={
        <>
          <ListChoice
            title="Oslo, Norway"
            onClick={(event) => setChoice(event.currentTarget.innerText)}
          />
          <ListChoice
            title="Prague, Czechia"
            onClick={(event) => setChoice(event.currentTarget.innerText)}
          />
          <ListChoice
            title="Milan, Italy"
            onClick={(event) => setChoice(event.currentTarget.innerText)}
          />
        </>
      }
      noPadding
    >
      <InputField label="To" inlineLabel value={choice} />
    </Popover>
  )
}

Don’t use list choices when the information for each choice is very different. This will slow down and confuse users.

Categorize with icons

When you have a lot of similar structures, breaking them into various groups makes it easier for users to choose. To show things like stations with different modes of transport, use different icons for each mode.

Just remember that not everyone will see your visual cues, so include the same information in a non-visual way.

import InputField from "@kiwicom/orbit-components/lib/InputField";
import ListChoice from "@kiwicom/orbit-components/lib/ListChoice";
import Popover from "@kiwicom/orbit-components/lib/Popover";
() => {
  const [choice, setChoice] = React.useState("")
  return (
    <Popover
      content={
        <>
          <ListChoice
            icon={<AirplaneUp ariaLabel="Airport" />}
            title="London City"
            onClick={(event) => setChoice(event.currentTarget.innerText)}
          />
          <ListChoice
            icon={<Bus ariaLabel="Bus station" />}
            title="Victoria Coach Station"
            onClick={(event) => setChoice(event.currentTarget.innerText)}
          />
          <ListChoice
            icon={<Bus ariaLabel="Bus station" />}
            title="Golders Green"
            onClick={(event) => setChoice(event.currentTarget.innerText)}
          />
          <ListChoice
            icon={<Train ariaLabel="Train station" />}
            title="Paddington"
            onClick={(event) => setChoice(event.currentTarget.innerText)}
          />
          <ListChoice
            icon={<Train ariaLabel="Train station" />}
            title="Victoria"
            onClick={(event) => setChoice(event.currentTarget.innerText)}
          />
        </>
      }
      noPadding
    >
      <InputField label="To" inlineLabel value={choice} />
    </Popover>
  )
}

Add context with description

When the structure of each choice is similar, you can add additional context to the choices with the descriptions. For example, you can note how far each station is from the city center.

Just remember to keep the descriptions parallel so they are easy to skim through and find the information they need (such as the distance).

import InputField from "@kiwicom/orbit-components/lib/InputField";
import ListChoice from "@kiwicom/orbit-components/lib/ListChoice";
import Popover from "@kiwicom/orbit-components/lib/Popover";
() => {
  const [choice, setChoice] = React.useState("")
  return (
    <Popover
      content={
        <>
          <ListChoice
            title="London Heathrow"
            description="23 km from city center"
            onClick={(event) =>
              setChoice(event.currentTarget.children[0].children[0].innerText)
            }
          />
          <ListChoice
            title="London Gatwick"
            description="48 km from city center"
            onClick={(event) =>
              setChoice(event.currentTarget.children[0].children[0].innerText)
            }
          />
          <ListChoice
            title="London Stansted"
            description="68 km from city center"
            onClick={(event) =>
              setChoice(event.currentTarget.children[0].children[0].innerText)
            }
          />
        </>
      }
      noPadding
    >
      <InputField label="To" inlineLabel value={choice} />
    </Popover>
  )
}

The descriptions are presented as secondary text, so they should be used only for extra context and not vital information.

Use separately

List choices work well when separated from the main flow, such as in a popover, modal, or drawer. They don’t work as well within the context of other information, such as directly in a form (they can be in popovers within the form).

When using within a container like a popover, remove the extra padding added by the container (such as by using `noPadding` for a popover).

Explain any disabling

Similarly as with buttons, it’s best to avoid disabling any potential choices. When users see things that look like actions but they can’t take them, they may get confused.

If it’s necessary to present a disabled choice, make sure users know why the options aren’t available.

Related components

List

List choices present structured choices. If you only need simple items, consider using a list.

Checkbox/Radio

List choices present similar choices with the same structure. If your choices don’t require structure, consider using checkboxes or radio buttons.

Select

List choices present many structured choices, often where you can choose multiple choices. To present options in a more compact way for small spaces where only only choice can be selected, use a select.