Extra

ExposedDropdownMenu

A FormaUI exposed dropdown menu (autocomplete) — a FormaTextField anchor that drops a menu of options below it, delegating to Material 3's ExposedDropdownMenuBox. Fully hoisted (query text, expanded state, and the already-filtered options are the caller's); FormaUI provides the wiring, the rotating chevron, and the option rows. Generic over the option type via optionLabel.

3 variantsThemed defaults

import dev.formaui.components.autocomplete.FormaExposedDropdownMenu

Editable (type-to-filter)Non-editable (tap-to-select)Empty (No matches)

Preview

This toggle is site chrome only — the preview has its own light/dark switch inside.

LIVE PREVIEW

Live preview — ~37 MB development build

Usage

KOTLIN

12345678910111213var text by remember { mutableStateOf("") }
var expanded by remember { mutableStateOf(false) }
val matches = countries.filter { it.contains(text, ignoreCase = true) }
FormaExposedDropdownMenu(
    expanded = expanded,
    onExpandedChange = { expanded = it },
    value = text,
    onValueChange = { text = it },
    options = matches,
    onOptionSelected = { text = it },
    optionLabel = { it },
    label = "Country",
)

FormaExposedDropdownMenu

Generic <T> autocomplete: caller owns value/onValueChange, expanded/onExpandedChange, and the pre-filtered options; editable=true is a type-to-filter field (PrimaryEditable), editable=false is a read-only tap-to-select field (PrimaryNotEditable). Empty options while expanded shows a disabled 'No matches' row.

ParameterTypeDefaultDescription

expandedrequiredTypeBooleanDefaultrequiredDescriptionwhether the menu is currently open.

onExpandedChangerequiredType(Boolean) -> UnitDefaultrequiredDescriptioncalled when the menu requests to open or close (anchor tap, dismiss).

valuerequiredTypeStringDefaultrequiredDescriptionthe current query / selected text shown in the anchor field.

onValueChangerequiredType(String) -> UnitDefaultrequiredDescriptioncalled as the user edits the query. Only fires while editable is true.

optionsrequiredTypeList<T>DefaultrequiredDescriptionthe options to show, already filtered by the caller for the current value.

onOptionSelectedrequiredType(T) -> UnitDefaultrequiredDescriptioncalled with the chosen option when a row is tapped; the menu then collapses. The caller reflects the choice into value (e.g. value = optionLabel(it)).

optionLabelrequiredType(T) -> StringDefaultrequiredDescriptionmaps an option to its display (and menu-row) text.

modifierTypeModifierDefaultModifierDescriptionthe Modifier applied to the ExposedDropdownMenuBox.

variantTypeFormaTextFieldVariantDefaultFormaTextFieldVariant.OutlinedDescriptionthe anchor field's container style (defaults to FormaTextFieldVariant.Outlined).

editableTypeBooleanDefaulttrueDescriptionwhether the field is a type-to-filter autocomplete (true) or a read-only tap-to-select field (false).

enabledTypeBooleanDefaulttrueDescriptionwhether the control is interactive (disables both the field and the menu anchor).

labelTypeString?DefaultnullDescriptionoptional floating label on the anchor field.

placeholderTypeString?DefaultnullDescriptionoptional placeholder shown while the field is empty.

isErrorTypeBooleanDefaultfalseDescriptionwhether the anchor field is in the error state.

helperTextTypeString?DefaultnullDescriptionoptional supporting text shown below the field when not in error.

errorTextTypeString?DefaultnullDescriptionoptional supporting text shown below the field while isError is true.

leadingIconType@Composable (() -> Unit)?DefaultnullDescriptionoptional slot at the start of the anchor field.

colorsTypeTextFieldColors?DefaultnullDescriptionthe anchor field colors. When null, the M3 defaults for the variant are used.

noMatchesTextTypeStringDefaultFormaExposedDropdownMenuDefaults.NoMatchesTextDescriptionthe label of the single disabled row shown when options is empty while expanded (defaults to FormaExposedDropdownMenuDefaults.NoMatchesText, "No matches").

Supporting API

FormaExposedDropdownMenuDefaultsobject: Defaults for FormaExposedDropdownMenu: NoMatchesText ("No matches") — the label of the disabled empty-options row.

Accessibility

The rotating chevron trailing icon and the anchor's expand/collapse + option semantics are handled by Material 3's ExposedDropdownMenuBox / menuAnchor; the trailing icon is the standard M3 ExposedDropdownMenuDefaults.TrailingIcon. The field's error state is surfaced to accessibility services by the underlying FormaTextField.

PreviousEmptyState Next FloatingActionButton