PopupSelector

A sleek, fluid morphing popup selector component for Compose Multiplatform (Android, JVM/Desktop, iOS).

📦 Download Demo APK

• 🪶 Zero External Dependencies: Built exclusively on Compose Foundation and Material 3.
• 🪄 Fluid Morphing Animation: Seamless continuous transition between the collapsed button and the expanded floating surface.
• 🛫 Flying Selected Item: The selected item visibly flies from the trigger button into its position inside the expanded list.
• 🧭 Smart Direction Resolution: Each axis picks its side from the available space — centring on the current selection, hugging the leading edge, or pinning an explicit side (Top/Bottom, Start/End) via PopupVerticalAlignment / PopupHorizontalAlignment.
• ⌨️ Keyboard Navigation: Arrow keys move the cursor, Enter/Space select, Esc dismisses. Fully operable on desktop.
• 🎨 Deep Customization: Fully customizable colors, corner radius, heights, widths, and item slots.
• 🧩 Pluggable Visual Effects: Attach frosted-glass blur (Haze / Blur) or custom backgrounds via anchorModifier and surfaceModifier.
• 🧱 Fully Overridable Metrics: Every size, spacing and animation threshold is a plain data class you can replace wholesale.

In your module's build.gradle.kts (e.g., commonMain):

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.viel0320:popupselector:2.1.0")
        }
    }
}

The library is also published to GitHub Packages. GitHub's Maven registry requires authentication even for public packages, so declare the repository with credentials (a GitHub username plus a token with read:packages) in your settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("https://maven.pkg.github.com/Viel0320/Popupselector")
            credentials {
                username = findProperty("gpr.user") as String? ?: System.getenv("GITHUB_ACTOR")
                password = findProperty("gpr.key") as String? ?: System.getenv("GITHUB_TOKEN")
            }
        }
    }
}

import androidx.compose.runtime.*
import com.viel.compose.popupselector.*

@Composable
fun FilterSelector() {
    var expanded by remember { mutableStateOf(false) }
    var selectedIndex by remember { mutableStateOf<Int?>(0) }

    val items = remember {
        listOf(
            textPopupItem(key = "all", label = "All Items", count = 128),
            textPopupItem(key = "favorites", label = "Favorites", count = 12),
            textPopupItem(key = "archived", label = "Archived", count = 3),
            textPopupItem(key = "trash", label = "Trash", enabled = false),
        )
    }

    PopupSelector(
        items = items,
        expanded = expanded,
        selectedIndex = selectedIndex,
        onExpandedChange = { expanded = it },
        onSelect = { selectedIndex = it },
        layout = PopupLayout(width = PopupWidth.Wrap),
    )
}

You can provide fully customized item composables for each option:

val items = remember {
    listOf(
        PopupItem(
            key = "daily",
            count = { Text("7:00 AM", style = MaterialTheme.typography.bodySmall) },
        ) {
            Row(verticalAlignment = Alignment.CenterVertically) {
                Icon(Icons.Default.Today, contentDescription = null)
                Spacer(Modifier.width(8.dp))
                Text("Daily Digest")
            }
        },
        PopupItem(key = "weekly") {
            Row(verticalAlignment = Alignment.CenterVertically) {
                Icon(Icons.Default.DateRange, contentDescription = null)
                Spacer(Modifier.width(8.dp))
                Text("Weekly Summary")
            }
        },
    )
}

PopupSelector(
    items = items,
    expanded = expanded,
    selectedIndex = selectedIndex,
    onExpandedChange = { expanded = it },
    onSelect = { selectedIndex = it },
    layout = PopupLayout(width = PopupWidth.Fixed(280.dp)),
)

Set via PopupLayout(width = ...). Three strategies are available:

Set via PopupLayout(verticalAlignment = ..., horizontalAlignment = ...). The two axes resolve independently, so the panel can, say, open downward while hugging the trailing edge.

Vertical — PopupVerticalAlignment:

• Auto: (Default) With a selection, aligns the selected row's vertical centre with the trigger's centre, so the current selection stays put as the panel opens. Without a selection, compares the room above and below and picks the side that fits.
• Top / Bottom: Pin the panel to that side of the trigger.

Horizontal — PopupHorizontalAlignment:

• Auto: (Default) Hugs the trigger's leading side when both sides fit; opens toward the only side with room. Mirrors with the layout direction.
• Start / End: Pin a direction-aware side (mirrors in RTL).

Both axes also offer Inherit, which follows the matching component of LocalPopupAlignment — the ambient alignment a subtree provides with CompositionLocalProvider (typically alongside a Box(contentAlignment = ...)), falling back to Auto when none is provided.

Explicit placements are honoured whether or not an item is selected. Only Auto repositions the panel vertically to match the selection.

You can customize the content inside the collapsed button (ideal for dropdown action menus). collapsedContent is the last parameter, so it can be passed as a trailing lambda:

PopupSelector(
    items = menuItems,
    expanded = expanded,
    onExpandedChange = { expanded = it },
    onSelect = { index -> handleMenuAction(index) },
) {
    Text("Actions Menu", fontWeight = FontWeight.Bold)
}

To use real-time blur libraries like Haze, wrap your root layout in PopupOverlayContainer (or PopupOverlayHost) so the panel shares the same window and drawing tree with hazeSource (isolated native Popup windows cannot sample parent pixels). Combine with PopupDefaults.blurColors() for preconfigured transparent surfaces.

val rootHazeState = remember { HazeState() }
val parentHazeState = remember { HazeState() }

// Wrap your root/screen in PopupOverlayContainer to enable seamless in-window blur sampling
PopupOverlayContainer(Modifier.fillMaxSize()) {
    // 1. Root layer registered as hazeSource (for expanded panel & full-screen blur)
    Column(
        modifier = Modifier
            .fillMaxSize()
            .hazeSource(rootHazeState)
            .padding(16.dp)
    ) {
        // 2. Direct parent container with background registered as hazeSource (for collapsed anchor button)
        Box(
            modifier = Modifier
                .background(Color.Blue.copy(alpha = 0.3f), RoundedCornerShape(12.dp))
                .hazeSource(parentHazeState)
                .padding(16.dp)
        ) {
            PopupSelector(
                items = items,
                expanded = expanded,
                selectedIndex = selectedIndex,
                onExpandedChange = { expanded = it },
                onSelect = { selectedIndex = it },
                style = PopupDefaults.style(colors = PopupDefaults.blurColors()),
                anchorModifier = Modifier.hazeEffect(state = parentHazeState, style = HazeMaterials.ultraThin()),
                surfaceModifier = Modifier.hazeEffect(state = rootHazeState, style = HazeMaterials.ultraThin()),
            )
        }
    }
}

All values are @Stable data class fields, so you can override any subset:

collapsedHeight (32.dp) · collapsedTouchTarget (48.dp) · rowTouchTargetHeight (48.dp) · rowVerticalSpacing (4.dp) · panelVerticalPadding (8.dp) · collapsedHorizontalPadding (16.dp) · rowHorizontalPadding (12.dp) · chevronLeadingPadding (8.dp) · countSpacing (12.dp) · borderWidth (1.dp) · chevronSize (18.dp) · rowEnterTranslation (14.dp) · edgeMargin (8.dp) · maxHeightFraction (0.6f) · disabledAlpha (0.38f) · corner (8.dp) · collapsedElevation (0.dp) · expandedElevation (6.dp)

visibleEpsilon (0.0001f) · morphCompleteThreshold (0.999f) · chevronExpandFadeSpan (0.25f) · chevronCollapseFadeSpan (0.25f) · staggerBase (0.15f) · staggerStep (0.06f) · staggerMax (0.6f) · borderMinWidth (0.25f) · containerMinAlpha (0.001f) · shadowStartFraction (0.85f) · anchorHighlightFadeMillis (90 ms)

shadowStartFraction delays the expanding surface's shadow until the morph is that far along, so a low-elevation shadow doesn't read as a dark rim around transparent containers — set 0f for an always-on ramp. anchorHighlightFadeMillis is the collapsed trigger's press/hover highlight fade duration.

The expanded panel takes focus automatically and supports:

Disabled options are skipped by arrow-key navigation. While the panel collapses, its rows leave the accessibility tree, and the surface unmounts entirely once collapsed, so the fading panel is never announced. The collapsed trigger announces its expansion state via stateDescription ("Expanded" / "Collapsed"); Compose currently has no localizable expanded-state semantic property, so these strings are supplied by the library in English.

Copyright 2026 Viel

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.