Maturity
Types
Combobox comes in two flavors:
Maturity
FYQ2 target
Figma component
Repository
Storybook
Combobox Field (preferred)
Is a Field composition that wraps a Combobox Control. This is the preferred component as it has all the elements needed to make the Combobox Control usable and accessible.
Anatomy
A combobox control is an interactive element that enables users to type and select from a list of choices. It supports single or multiple selections.
Properties
Name |
Values |
Default |
---|---|---|
Size |
MD SM |
MD |
Disabled |
boolean |
false |
Read-only |
boolean |
false |
Empty |
boolean |
True |
Error |
boolean |
False |
Draggable |
boolean |
false |
Type |
Single-select |
multiple |
TagsGroup |
Inline |
stacked |
Creatable |
boolean |
false |
How to use
Number of choices
The recommended number of choices in the Combobox ranges from 30 options to an infinite selection. The purpose of this component is to accommodate a wide range of choices while minimizing clutter on crowded interfaces.
Tag display
When the Combobox enables multiple selections, the control showcases the selected options as tags. These tags can be arranged either in a stacked or inline manner, depending on the context.
Behavior
States
The state of a component can depend on properties set before people can interact with it. We call them state properties. Differentiating them from the user-triggered states allows us to combine them, creating richer states that cover the whole interaction spectrum.
Related content
Default variants
Error variants
ReadOnly
When the property ReadOnly is true, people can't edit the control.
ReadOnly displays values in an accessible way so that users can read them. ReadOnly control can be focused and hovered but can’t be edited. Displays some visual signifiers, like a lock icon and neutral shades, that help the users to identify its status. Finally, ReadOnly does not participate in the form validation.
Use this control state in cases where the user, for example, does not have the right to edit the content. If you need an empty control, use the Disabled state.
Disabled
When the property Disabled is true, users can't edit the control. Disabled can display a value or an empty control and do not necessarily needs to pass accessibility standards. Disabled displays some visual signifiers, like a lock icon and neutral shades, that help the users to identify their status. Finally, disabled status does not participate in the form validation.
Draggable
When the property Draggable is true, the control shows an icon that signifies it can be draggable. While it's being grabbed, the container gets the Awake Hovered shadow effect.
Tag order
Tags order on the Combobox control is displayed from left to right and from bottom to top. The last tag added to the control is the first displayed on the list. This behavior is consistent with the Choice menu, where the last item added or selected is also displayed at the top of the list.
Value types
There are two types of values that can be displayed on the combobox.
- When is single-select, the control displays Value Label .
- When is multi-select, the control diaplys Tags
Typing custom values
Combobox allows users to type random values on the control
Autocomplete
As the user types, the Choice Menu items are dynamically sorted to match the user's input value. This matching process is visually represented by an underlying indicator highlighting the letters that match the user's input.
Creating custom values
When the Creatable property is activated, users have the ability to add custom values to the control. There are three different ways in which custom values can be added once the value is typed in:
- Pressing the enter key.
- Writing a comma followed by a space.
- Clicking the "Create" action displayed on the choice menu.
No data state
When the Creatable property is disabled, users will encounter an empty state in the choice menu if they type a value that is not present in the list.
Width
Full-width
Combobox control fills the container where is displayed until reaching a limit. This helps to make our form layouts more visually compensated with the rest of the elements.
Min-width
The Combobox Control has a 120px min-width.
Height
Stacked
The TagGroup property Stacked allows combobox controls to grow in height. If the number of tags on the control exceeds the 96px height, the control stops growing and displays a scrollbar.
Inline
The TagGroup property Inline fixes the height in the Combobox control. If the number of tags on the control exceeds the available space, the control displays a tag with the number of tags hidden.
Quality checklist
This component passes the Beta quality checklist described in our Component lifecycle.
Maturity
α · Design tokens
It uses Ariane design tokens.
α · Official assets
It uses the official Ariane assets (e.g., icons and illustrations) in one of the official sizes.
α · Accessible use of color
Its color contrast ratio is at least 4.5:1 for text and interactive areas.
α · Target areas
Its interactive target areas are large enough for users to accurately select them, following the Fitts law.
α · Naming agreement
Its name is agreed upon and shared between design and development.
α · Responsive L1
Is responsive to different viewport sizes.
α · User-triggered states
If the component is interactive, all its possible user-triggered interactive states are defined.
β · Responsive L2
The responsive behavior has been reviewed and validated by the team.
β · State properties
All the possible state attributes are defined.
β · Docs L1
It has essential documentation with at least primary usage.
β · Use cases
All the uses are audited and refined.
RC · Definition agreement
Its naming and properties are audited and aligned in design and code.
RC · Accessible L1
Its accessibility is manually audited, and any significant issues are fixed.
RC · Docs L2
The documentation covers the most common use cases and is expected to be iterated during the Release Candidate phase.
Stable · Stable API
The component and its API remain stable, with no breaking changes for at least one month.
Stable · Adaptive
Supports adaptive design via preference queries.
Stable · Docs L3
Detailed documentation exists for design, content, accessibility, and implementation, including do’s and dont’s.
Stable · Tooling
Tooling (such as linters, codemods, etc.) exists to help with migrations and prevent further use of alternatives.