ListPopup

ListPopup is a popup list component in Miuix used to display a popup menu with multiple options. It provides a lightweight, floating temporary list suitable for various dropdown menus, context menus, and similar scenarios.

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

import top.yukonga.miuix.kmp.basic.ListPopup
import top.yukonga.miuix.kmp.basic.ListPopupColumn

Basic Usage

The ListPopup component can be used to create simple dropdown menus:

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

Scaffold {
    Box {
        TextButton(
            text = "Click to show menu",
            onClick = { showPopup.value = true }
        )
        ListPopup(
            show = showPopup,
            alignment = PopupPositionProvider.Align.Left,
            onDismissRequest = { showPopup.value = false } // Close the popup menu
        ) {
            ListPopupColumn {
                items.forEachIndexed { index, string ->
                    DropdownImpl(
                        text = string,
                        optionSize = items.size,
                        isSelected = selectedIndex == index,
                        onSelectedIndexChange = {
                            selectedIndex = index
                            showPopup.value = false // Close the popup menu
                        },
                        index = index
                    )
                }
            }
        }
    }
}

Component States

Different Alignments

ListPopup can be set with different alignment options:

var showPopup = remember { mutableStateOf(false) }

ListPopup(
    show = showPopup,
    onDismissRequest = { showPopup.value = false } // Close the popup menu
    alignment = PopupPositionProvider.Align.Left
) {
    ListPopupColumn {
        // Custom content
    }
}

Disable Window Dimming

var showPopup = remember { mutableStateOf(false) }

ListPopup(
    show = showPopup,
    onDismissRequest = { showPopup.value = false } // Close the popup menu
    enableWindowDim = false // Disable dimming layer
) {
    ListPopupColumn {
        // Custom content
    }
}

Properties

ListPopup Properties

Property Name	Type	Description	Default Value	Required
show	MutableState<Boolean>	State object controlling popup visibility	-	Yes
popupModifier	Modifier	Modifier applied to the popup list	Modifier	No
popupPositionProvider	PopupPositionProvider	Position provider for the popup	ListPopupDefaults.DropdownPositionProvider	No
alignment	PopupPositionProvider.Align	Alignment of the popup list	PopupPositionProvider.Align.Right	No
enableWindowDim	Boolean	Whether to enable dimming layer	true	No
shadowElevation	Dp	Shadow elevation of the popup	11.dp	No
onDismissRequest	(() -> Unit)?	Callback when popup is dismissed	null	No
maxHeight	Dp?	Maximum height of the popup list	null (auto-calculated)	No
minWidth	Dp	Minimum width of the popup list	200.dp	No
content	@Composable () -> Unit	Content of the popup list	-	Yes

ListPopupDefaults Object

The ListPopupDefaults object provides default settings for the ListPopup component.

Properties

Property Name	Type	Description
DropdownPositionProvider	PopupPositionProvider	Position provider for dropdown scenarios
ContextMenuPositionProvider	PopupPositionProvider	Position provider for context menus

PopupPositionProvider Interface

The PopupPositionProvider interface defines methods for calculating popup list positions.

PopupPositionProvider.Align Options

Option Name	Description
Left	Align to the left of the window
Right	Align to the right of the window
TopLeft	Align above-left relative to the window
TopRight	Align above-right relative to the window
BottomLeft	Align below-left relative to the window
BottomRight	Align below-right relative to the window

Advanced Usage

Custom Content Layout

var showPopup = remember { mutableStateOf(false) }

Scaffold {
    Box {
        TextButton(
            text = "Click to show menu",
            onClick = { showPopup.value = true }
        )
        ListPopup(
            show = showPopup,
            minWidth = 250.dp,
            maxHeight = 300.dp,
            onDismissRequest = { showPopup.value = false } // Close the popup menu
            alignment = PopupPositionProvider.Align.BottomRight,
        ) {
            ListPopupColumn {
                Column(modifier = Modifier.padding(16.dp)) {
                    Text(
                        "Custom Title",
                    )
                    Spacer(modifier = Modifier.height(8.dp))
                    HorizontalDivider()
                    Spacer(modifier = Modifier.height(8.dp))
                    Text("This is a custom content popup menu. You can add various components as needed.")
                    Spacer(modifier = Modifier.height(16.dp))
                    Row(
                        modifier = Modifier.fillMaxWidth(),
                        horizontalArrangement = Arrangement.End
                    ) {
                        TextButton(
                            text = "Confirm",
                            onClick = { showPopup.value = false } // Close the popup menu
                        )
                    }
                }
            }
        }
    }
}

Changelog

Last edited 1 day ago

View full history

4007f40-docs: fix errors

9bda688-docs: Emphasize the use of MiuixPopupHost param

752f3df-docs: Preview for components in documentation website (#80)

0433c3c-library: Support custom dialog/popup layout anim (#71)

1fb088b-library: Refactor dialog/popup layout

7b99e64-docs: Add English version through AI translation

ab6bb69-chore: Add documents (#63)