Dropdown
Present a list of options to the user to select from.
Props
ariaLabel
string
Defines how the selected value will be translated for the screen reader.
ariaLabelledBy
string
The aria-labelledby attribute identifies the element that labels the dropdown. Normally it is the id of the label.
autoComplete
string
Specifies the autocomplete attribute for the dropdown input. Native only.
disabled
boolean
Disables the dropdown control.
error
boolean
Shows an error state on the dropdown.
filterable
boolean
When true, allows filtering options by typing into the input field.
id
string
The id attribute for the dropdown element.
leadingIcon
GoabIconType
Icon shown to the left of the dropdown input.
maxHeight
string
Maximum height of the dropdown menu. Non-native only.
Defaults to
276px.
maxWidth
string
Sets the maximum width of the dropdown. Use a CSS unit (px, %, ch, rem, em).
name
string
Identifier for the dropdown. If omitted, a unique name is generated.
native
boolean
When true, renders the native select HTML element.
noResults
string
Sets the text displayed when filtering returns no results.
Defaults to
No matches found.
placeholder
string
The text displayed in the dropdown before a selection is made. Non-native only.
size
GoabDropdownSize default | compact
Sets the size of the dropdown. Compact reduces height for dense layouts.
Defaults to
default.
testId
string
Sets a data-testid attribute for automated testing.
value
string[] | string
The value of the selected item.
width
string
Overrides the autosized menu width. Non-native only.
mt, mr, mb, ml
Spacing
Apply margin to the top, right, bottom, and/or left of the component.
Events
onBlur
(detail: GoabDropdownOnBlurDetail) => void
Callback fired when the dropdown loses focus.
onChange
(detail: GoabDropdownOnChangeDetail) => void
Callback fired when the selected value changes.
onFocus
(detail: GoabDropdownOnFocusDetail) => void
Callback fired when the dropdown receives focus.
Dropdown Item Props
value
string
The value submitted when this item is selected. Set to an empty string (`""`) to make this item the default selected value.
filter
string
Additional text used to match this item in typeahead search, alongside the label. Defaults to the content's text.
label
string
Display label for the dropdown item.
mountType
GoabDropdownItemMountType append | prepend | reset
Controls how the item is registered with the parent dropdown.
Defaults to
append.
testId
string
Sets a data-testid attribute for automated testing.
States
When you must disable a button or input:
- Provide nearby text explaining what needs to happen first
- Consider showing the element enabled with validation on submit instead
- Use aria-describedby to link the disabled element to explanatory text
Don't
Don't disable buttons or inputs without explaining why. Disabled controls can be confusing and users may not understand why they can't interact with an element.
Sizing
Do
Define dropdown widths based on the widest dropdown in the form.
Do
Use the default width for dropdowns. The dropdown automatically sets its width based on the length of the options.
Positioning
Don't
Don't allow the dropdown menu to hide below the viewport.
Content
Don't
Don't truncate labels. Longer labels should wrap to the next line.
Placeholder text disappears when users start typing, leaving them without context for what the field is asking for.
Always use a visible label above or beside the input field. Placeholder text can provide an example of the expected format, but should never be the only indication of what information is needed.
Don't
Don't use placeholder text as a label
Interaction
Tip
A filterable dropdown searches an item's label and the text of its content, but not text rendered inside a nested component such as a Badge. Use the filter property to add those terms to the search.
Types
Warning
The native dropdown renders a native select element, which cannot contain HTML. Items with rich content fall back to their label, so set a label on every item that you also give content to.
Other
The form item automatically associates the label with the input for screen readers, ensuring your form is accessible.
Do
Use a form item wrapper on all inputs to add a label, helper text, error message, and more.
Screen Readers
Warning
When a Dropdown is not wrapped in a FormItem, set ariaLabel to provide an accessible name. Without it, screen readers won't be able to identify the dropdown.
Accessibility
Warning
Don't put buttons, links, inputs, or other interactive elements in an item's content. Each item is a listbox option, so nested controls are not in the tab order and cannot be reached by keyboard, and clicking one selects the item instead of activating the control. Use text, icons, and badges instead.
