{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

ExposedDropdownMenuKt

public final class ExposedDropdownMenuKt


Summary

Public methods

static final void
@ExperimentalMaterial3Api
@Composable
ExposedDropdownMenuBox(
    boolean expanded,
    @NonNull Function1<@NonNull BooleanUnit> onExpandedChange,
    @NonNull Modifier modifier,
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull ExposedDropdownMenuBoxScopeUnit> content
)

Material Design Exposed Dropdown Menu.

Public methods

ExposedDropdownMenuBox

@ExperimentalMaterial3Api
@Composable
public static final void ExposedDropdownMenuBox(
    boolean expanded,
    @NonNull Function1<@NonNull BooleanUnit> onExpandedChange,
    @NonNull Modifier modifier,
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull ExposedDropdownMenuBoxScopeUnit> content
)

Material Design Exposed Dropdown Menu.

Menus display a list of choices on a temporary surface. They appear when users interact with a button, action, or other control.

Exposed dropdown menus, sometimes also called "spinners" or "combo boxes", display the currently selected item in a text field to which the menu is anchored. In some cases, it can accept and display user input (whether or not it’s listed as a menu choice), in which case it may be used to implement autocomplete.

Exposed dropdown menu image

The ExposedDropdownMenuBox is expected to contain a TextField (or OutlinedTextField) and ExposedDropdownMenu as content. The menuAnchor modifier should be passed to the text field.

An example of a read-only Exposed Dropdown Menu:

import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.ExposedDropdownMenuBox
import androidx.compose.material3.ExposedDropdownMenuDefaults
import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier

val options = listOf("Option 1", "Option 2", "Option 3", "Option 4", "Option 5")
var expanded by remember { mutableStateOf(false) }
var selectedOptionText by remember { mutableStateOf(options[0]) }
// We want to react on tap/press on TextField to show menu
ExposedDropdownMenuBox(
    expanded = expanded,
    onExpandedChange = { expanded = it },
) {
    TextField(
        // The `menuAnchor` modifier must be passed to the text field for correctness.
        modifier = Modifier.menuAnchor(),
        readOnly = true,
        value = selectedOptionText,
        onValueChange = {},
        label = { Text("Label") },
        trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = expanded) },
        colors = ExposedDropdownMenuDefaults.textFieldColors(),
    )
    ExposedDropdownMenu(
        expanded = expanded,
        onDismissRequest = { expanded = false },
    ) {
        options.forEach { selectionOption ->
            DropdownMenuItem(
                text = { Text(selectionOption) },
                onClick = {
                    selectedOptionText = selectionOption
                    expanded = false
                },
                contentPadding = ExposedDropdownMenuDefaults.ItemContentPadding,
            )
        }
    }
}

An example of an editable Exposed Dropdown Menu:

import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.ExposedDropdownMenuBox
import androidx.compose.material3.ExposedDropdownMenuDefaults
import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier

val options = listOf("Option 1", "Option 2", "Option 3", "Option 4", "Option 5")
var expanded by remember { mutableStateOf(false) }
var selectedOptionText by remember { mutableStateOf("") }
ExposedDropdownMenuBox(
    expanded = expanded,
    onExpandedChange = { expanded = it },
) {
    TextField(
        // The `menuAnchor` modifier must be passed to the text field for correctness.
        modifier = Modifier.menuAnchor(),
        value = selectedOptionText,
        onValueChange = { selectedOptionText = it },
        label = { Text("Label") },
        trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = expanded) },
        colors = ExposedDropdownMenuDefaults.textFieldColors(),
    )
    // filter options based on text field value
    val filteringOptions = options.filter { it.contains(selectedOptionText, ignoreCase = true) }
    if (filteringOptions.isNotEmpty()) {
        ExposedDropdownMenu(
            expanded = expanded,
            onDismissRequest = { expanded = false },
        ) {
            filteringOptions.forEach { selectionOption ->
                DropdownMenuItem(
                    text = { Text(selectionOption) },
                    onClick = {
                        selectedOptionText = selectionOption
                        expanded = false
                    },
                    contentPadding = ExposedDropdownMenuDefaults.ItemContentPadding,
                )
            }
        }
    }
}
Parameters
boolean expanded

whether the menu is expanded or not

@NonNull Function1<@NonNull BooleanUnit> onExpandedChange

called when the exposed dropdown menu is clicked and the expansion state changes.

@NonNull Modifier modifier

the Modifier to be applied to this ExposedDropdownMenuBox

@Composable @ExtensionFunctionType @NonNull Function1<@NonNull ExposedDropdownMenuBoxScopeUnit> content

the content of this ExposedDropdownMenuBox, typically a TextField and an ExposedDropdownMenu. The menuAnchor modifier should be passed to the text field for proper menu behavior.