OverlayDropdownPreference

OverlayDropdownPreference is a dropdown menu component in Miuix that provides a title, summary, and a list of dropdown options. It supports click interaction and is commonly used in option settings and list selections.

Prerequisite

This component depends on Scaffold providing MiuixPopupHost to render popup content. It must be used within Scaffold, otherwise popup content will not render correctly.

Import

kotlin

import top.yukonga.miuix.kmp.preference.OverlayDropdownPreference
import top.yukonga.miuix.kmp.basic.DropdownEntry
import top.yukonga.miuix.kmp.basic.DropdownItem

Basic Usage

The OverlayDropdownPreference component provides basic dropdown menu functionality:

kotlin

var selectedIndex by remember { mutableStateOf(0) }
val options = listOf("Option 1", "Option 2", "Option 3")

Scaffold {
    OverlayDropdownPreference(
        title = "Dropdown Menu",
        items = options,
        selectedIndex = selectedIndex,
        onSelectedIndexChange = { selectedIndex = it }
    )
}

kotlin

var selectedIndex by remember { mutableStateOf(0) }
val options = listOf("中文", "English", "日本語")

Scaffold {
    OverlayDropdownPreference(
        title = "Language Settings",
        summary = "Choose your preferred language",
        items = options,
        selectedIndex = selectedIndex,
        onSelectedIndexChange = { selectedIndex = it }
    )
}

Observe Expanded State

kotlin

var selectedIndex by remember { mutableStateOf(0) }
var expanded by remember { mutableStateOf(false) }
val options = listOf("Option 1", "Option 2", "Option 3")

Scaffold {
    OverlayDropdownPreference(
        title = "Dropdown Menu",
        summary = if (expanded) "Expanded" else "Collapsed",
        items = options,
        selectedIndex = selectedIndex,
        onExpandedChange = { expanded = it },
        onSelectedIndexChange = { selectedIndex = it }
    )
}

Custom Entries

Use DropdownEntry and DropdownItem when individual dropdown items need extra state, such as selection, callbacks, or disabling a specific option.

kotlin

var selectedIndex by remember { mutableStateOf(0) }
val entry = DropdownEntry(
    items = listOf(
        DropdownItem(text = "Option 1", selected = selectedIndex == 0, onClick = { selectedIndex = 0 }),
        DropdownItem(text = "Option 2", enabled = false),
        DropdownItem(text = "Option 3", selected = selectedIndex == 2, onClick = { selectedIndex = 2 }),
    )
)

Scaffold {
    OverlayDropdownPreference(
        title = "Dropdown Menu",
        entry = entry
    )
}

Disabled dropdown items are not clickable and their text and selected indicator use the disabled color.

Use entries to show multiple dropdown groups separated by dividers. Each item keeps its own selected state and click callback.

kotlin

var firstSelectedIndex by remember { mutableStateOf(0) }
var secondSelectedIndex by remember { mutableStateOf(0) }
val entries = listOf(
    DropdownEntry(
        items = listOf("Small", "Medium").mapIndexed { index, text ->
            DropdownItem(text = text, selected = firstSelectedIndex == index, onClick = { firstSelectedIndex = index })
        }
    ),
    DropdownEntry(
        items = listOf("Red", "Green", "Blue").mapIndexed { index, text ->
            DropdownItem(text = text, selected = secondSelectedIndex == index, onClick = { secondSelectedIndex = index })
        }
    )
)

Scaffold {
    OverlayDropdownPreference(
        title = "Grouped Dropdown",
        entries = entries,
        collapseOnSelection = false
    )
}

For the entries overload, collapseOnSelection controls whether the popup closes after an item is selected. It defaults to entries.size <= 1, so a single group closes after selection while multiple groups stay open for consecutive changes.

Multi Select

Because selection state lives on DropdownItem, multiple items can be selected by keeping a set of selected values and toggling each item from onClick.

kotlin

var selectedItems by remember { mutableStateOf(setOf("A1", "B2")) }
val entries = listOf(
    DropdownEntry(
        items = listOf("A1", "A2").map { text ->
            DropdownItem(
                text = text,
                selected = text in selectedItems,
                onClick = {
                    selectedItems = if (text in selectedItems) selectedItems - text else selectedItems + text
                }
            )
        }
    ),
    DropdownEntry(
        items = listOf("B1", "B2", "B3").map { text ->
            DropdownItem(
                text = text,
                selected = text in selectedItems,
                onClick = {
                    selectedItems = if (text in selectedItems) selectedItems - text else selectedItems + text
                }
            )
        }
    )
)

Scaffold {
    OverlayDropdownPreference(
        title = "Multi Select Dropdown",
        entries = entries,
        collapseOnSelection = false
    )
}

Component States

Disabled State

kotlin

OverlayDropdownPreference(
    title = "Disabled Dropdown",
    summary = "This dropdown menu is currently unavailable",
    items = listOf("Option 1"),
    selectedIndex = 0,
    onSelectedIndexChange = {},
    enabled = false
)

Properties