Component comparison
EUI currently offers over 4 ways to select an option from a list (6 including checkboxes and radios).
Choosing the right selection component may seem tricky at first - with so many similar options, it can feel overwhelming figuring out which component to use. This comprehensive guide will help you decide which component to use and when, including detailed explanations and comparisons for each component.
Summary
When choosing a selection component, consider these key factors:
- Number of options: small sets (<7) work well with radio/checkbox groups, medium sets (<12) with EuiSelect, and larger sets need search functionality.
- Selection type: single vs. multiple selection requirements.
- Display needs: whether you need custom option rendering or simple text options.
- User input: whether users should be able to add custom values.
- Accessibility: native components (EuiSelect, radio/checkbox groups) are generally more accessible.
- Visual layout: horizontal pills (EuiComboBox) vs. vertical lists (EuiSelectable).
For most use cases, start with the simpler native components (EuiSelect, EuiRadioGroup, EuiCheckboxGroup) and only move to more complex components when you need their specific features.
Which selection component should I use?
The following decision tree will help you choose the right component based on your specific needs.
Single selection
- When you have a small set of options (<7) and all options are equally important in terms of visibility, use EuiRadioGroup.
- When you have a small set of options (<12) and only the current selected option has UI importance, reach for EuiSelect first when possible, over other more complex selection components.
- EuiSelect renders a basic HTML
<select>
element, providing the best cross-browser and cross-device affordances (particularly for mobile devices). - Native form controls are more familiar to end users due to their ubiquity across the internet.
- When you have a small set of options (<12) and if you need to customize how the options are rendered and selected, use EuiSuperSelect.
- EuiSuperSelect gives you control over option display through the
dropdownDisplay
prop, allowing for multi-line option text or descriptions. - We recommend reaching for EuiSuperSelect only if custom option display is absolutely necessary, as EuiSelect is natively more accessible.
- Large sets of options (>12) should use a selection component that supports searching/filtering options. This requires the use of one of the more advanced multiselect components with
singleSelection
set.
Multiple selections
- When you have a small set of options (<7), and all options are equally important in terms of visibility, use EuiCheckboxGroup.
- In general, we recommend using EuiSelectable for most multi-selection purposes. It renders a searchable, vertically-oriented list with icons next to the option representing selection state.
- EuiSelectable can optionally be rendered with a search box for filtering through many options, or as just a list for fewer options.
- EuiSelectable is by far our most accessible and flexible selection component (although customization may require extra development). It can be used within popovers and flyouts, or as a standalone list.
- If you need the ability to exclude options, EuiSelectable is the only component that offers that functionality.
- In general, for multi-select scenarios, we recommend using EuiComboBox over EuiSelectable primarily when selections should be immediately visible and unselected options should not. Selections are rendered as a horizontally-oriented list of pills.
- EuiComboBox allows users to search through a list of dropdown options. This functionality is core to the component and cannot be removed, unlike EuiSelectable.
- If you need the ability to dynamically add custom user-generated input outside of the available options, EuiComboBox is the only component that offers that functionality.
Feature comparison chart
Below is a handy reference for comparing the selection components.
Feature | ||||
---|---|---|---|---|
Select a single option | ✅ | ✅ | ✅ | ✅ |
Select multiple options | ❌ | ❌ | ✅ | ✅ |
Accepts custom values from user input | ❌ | ❌ | ❌ | ✅ |
Option exclusion | ❌ | ❌ | ✅ | ❌ |
Customizable option display | ❌ | ✅ | ✅ | ✅ |
Customizable loading/error messages | ❌ | ❌ | ✅ | ❌ |
Searchable | ❌ | ❌ | ✅ | ✅ |
disabled state | ✅ | ✅ | ✅ | ✅ |
readOnly state | ❌ | ✅ | ❌ | ❌ |
Built in utility function for clearing user input | ❌ | ❌ | ✅ | ✅ |
Supports virtualization | ❌ | ❌ | ✅ | ✅ |