ComboBox

A control that allows users to type and select single and multiple choices from a Choice menu

Cover

Types

Combobox comes in two flavors:

Maturity

-

FYQ2 target

🅽 Discovery

Figma component

-

Repository

-

Storybook

-

Combobox Control

Is bare-bones and does not have a Label or Helper text. You should only use this in rare situations where you add your custom Label or Helper text

Maturity

-

FYQ2 target

🅽 Discovery

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.

 

Anatomy of a Combobox control

Anatomy of a Combobox control

1. Placeholder
2. Draggable signifier
3. Display Choice Menu signifier
4. Disabled/Readonly signifier
5. Error signifier
6. Text error
7. Text Value
8. Tags group inline
9. Tags group stacked
10. Choice Menu display affordance
11. Choice Menu

 

 

Properties

Name

Values

Default

Size
Visual height and padding

MD SM

MD

Disabled
Disables interaction

boolean

false

Read-only
Disables interaction and focus and signifies it

boolean

false

Empty
Represents the default state of the control.

boolean

True

Error
Signifies the control is empty or with not allowed data

boolean

False

Draggable
Allows the control to be draggable

boolean

false

Type
Controls if the multiple or single selection is available

Single-select

multiple

TagsGroup
Controls if multiple tags display inline or stacked

Inline

stacked

Creatable
Controls if the user can add custom items

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.

 

⛔️ Avoid using combobox for short lists

⛔️ Avoid using combobox for short lists

The most straightforward approach to assisting users in making a selection is by displaying a short list of options upfront

✅ Use combobox for long list of options

✅ Use combobox for long list of options

Helping users to type and filter options will ease the selection process.

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.

✅ Use Stacked property as a default

✅ Use Stacked property as a default

Apply Stacked tags to allow the combobox control to expand in height and provide seamless interaction and navigation.

✅ Use inline property on dense contexts

✅ Use inline property on dense contexts

Apply the inline property in dense contexts to optimize space usage

 


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

Default

Error variants

Error

ReadOnly

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

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

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

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

Value type

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

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

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:

  1. Pressing the enter key.
  2. Writing a comma followed by a space.
  3. Clicking the "Create" action displayed on the choice menu.

No data state

Empty

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

FullWidth

FullWidth

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

min width

The Combobox Control has a 120px min-width.

Height

Stacked

Max 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

Max height- 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.