OverlayCascadingListPopup

OverlayCascadingListPopup is a popup list that supports a two-level cascading menu. Items whose DropdownItem.children is non-empty become submenu triggers; tapping such an item morphs the popup into a secondary list anchored at the trigger row, while the primary list scales down behind a translucent mask. Cascading depth is limited to 2.

Prerequisite

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

Import

kotlin

import io.github.suqi8.coui.kmp.overlay.OverlayCascadingListPopup
import io.github.suqi8.coui.kmp.basic.DropdownEntry
import io.github.suqi8.coui.kmp.basic.DropdownItem
import io.github.suqi8.coui.kmp.basic.PopupPositionProvider

Basic Usage

Build entries so that some DropdownItems carry a non-empty children list. The component renders a chevron next to such trigger rows; tapping the trigger expands the second level inline.

kotlin

var showPopup by remember { mutableStateOf(false) }
var sortIndex by remember { mutableStateOf(0) }
var viewIndex by remember { mutableStateOf(0) }

val sortLabels = listOf("Sort by capture date", "Sort by date added")
val viewLabels = listOf("Group by date", "Compact")
val entries = listOf(
    DropdownEntry(
        items = sortLabels.mapIndexed { idx, label ->
            DropdownItem(
                text = label,
                selected = sortIndex == idx,
                onClick = { sortIndex = idx },
            )
        },
    ),
    DropdownEntry(
        items = listOf(
            DropdownItem(
                text = "View mode",
                children = viewLabels.mapIndexed { idx, label ->
                    DropdownItem(
                        text = label,
                        selected = viewIndex == idx,
                        onClick = { viewIndex = idx },
                    )
                },
            ),
        ),
    ),
)

Scaffold {
    Box {
        TextButton(
            text = "Click to show menu",
            onClick = { showPopup = true },
        )
        OverlayCascadingListPopup(
            show = showPopup,
            entries = entries,
            onDismissRequest = { showPopup = false },
        )
    }
}

Cascading Depth

Cascading depth is capped at 2. Items at the secondary level cannot have their own children; deeper trees are silently ignored.

Component States

Different Alignments

kotlin

OverlayCascadingListPopup(
    show = showPopup,
    entries = entries,
    onDismissRequest = { showPopup = false },
    alignment = PopupPositionProvider.Align.Start,
)

Disable Window Dimming

kotlin

OverlayCascadingListPopup(
    show = showPopup,
    entries = entries,
    onDismissRequest = { showPopup = false },
    enableWindowDim = false,
)

By default the popup closes when the user picks any leaf item. Set collapseOnSelection = false to keep it open (e.g., for multi-select within a submenu).

kotlin

OverlayCascadingListPopup(
    show = showPopup,
    entries = entries,
    onDismissRequest = { showPopup = false },
    collapseOnSelection = false,
)

Selected Item Marking

Leaf items with selected = true show a trailing check icon tinted with DropdownColors.selectedIndicatorColor; submenu trigger rows always show a trailing chevron instead.

kotlin

DropdownItem(
    text = "Sort by date added",
    selected = true, // Marks this leaf with a trailing check icon
    onClick = { /* ... */ },
)

Back handling mirrors the outside-tap rule: while the secondary list is shown, a back gesture (or a tap outside the popup, or a tap on the cloned submenu header) collapses the secondary back into the primary list; at the primary level, back and outside taps dismiss the popup via onDismissRequest. Predictive back gestures preview the collapse/dismiss and restore the popup when cancelled — no extra configuration is needed.

Properties