errorMessage

A combo box can be marked as having an error to show that a value needs to be entered or that a value is invalid, prompting the user to correct their input before moving forward.

helpText

A combo box can have help text below the field to give extra context or instruction about what a user should input in the field. The help text communicates a hint or helpful information, such as specific requirements for correctly filling out the field.

description

Items within ComboBox also allow for additional content used to better communicate options. Icons, avatars, and descriptions can be added to the children of item. If a description is added, the prop slot="description" must be used to distinguish the different <Text> elements. See demo.

isReadOnly

Combo boxes have a read-only option for when content in the disabled state still needs to be shown. This allows for content to be copied, but not interacted with or changed. A combo box does not have a read-only option if no selection has been made.

isDisabled

A combo box in a disabled state shows that an input field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that it may become available later.

isError

A combo box can be marked as having an error to show that a value needs to be entered in order to move forward, or that a value that was entered is invalid.

menuTrigger

There are 3 options for how a combo box's menu can be triggered: when a user starts typing ("input"), when focus is placed on the input field ("focus"), and manually when the user clicks or taps the field button ("manual"). These are used for different degrees of the information complexity and/or user familiarity of menu options.

By default, the menu is triggered when a user starts typing. This should be used when the content is readily familiar or commonplace enough to a user that they can begin populating values without seeing a list of all available options.

If the content of the combo box is unfamiliar or complex, the menu should be triggered when focus is placed on the input field because a user would benefit from seeing example content before selecting a value.

If the content of the combo box is highly familiar and autocomplete is sufficient to surface options, the menu can be set to trigger manually.

hasAutocomplete

Combo boxes can automatically complete suggested results within the input field.

isRequired and necessityIndicator

Combo boxes can be marked as optional or required, depending on the situation. For required combo boxes, there are two styling options: a "(required)" label or an asterisk. If you use an asterisk, be sure to include hint text to explain what the asterisk means. Optional combo boxes are either denoted with text added to the end of the label — "(optional)" — or have no indication at all.

size

Combo boxes come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page.

width

The width of a combo box can be customized appropriately for its context. By default, it uses field-default-width-[small/medium/large/extra-large].

value

The value shows a user's entered text or the option they've selected.

label and hideLabel

Combo boxes should always have an accessible name, typically provided by a visible text label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the visible label may be hidden. When no visible label is present, the input must still expose an accessible name (for example, in HTML via "aria-label" or "aria-labelledby," and on other platforms via the platform's accessible-name mechanism).

labelPosition

Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited.