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
Web (React)
iOS (Swift)
Android (Kotlin)
DocsContent structure
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.