PopBox

A zero-boilerplate, fully parameterized Dialog for Compose Multiplatform. Manage your dialogs globally with a simple controller API, without polluting your UI logic with state management.

🚀 Features

• Multiplatform Support: Android, iOS, Desktop (JVM), and Web (Wasm/JS).
• Global Hosting: Define your PopBoxHost once at the root; trigger dialogs from anywhere.
• Stacked Dialogs: Open multiple dialogs on top of each other with built-in stack management.
• Full Customization: Control shapes, colors, and padding via PopBoxParams.
• Type-Safe: Built with Kotlin and modern Compose Multiplatform practices.
• Zero Boilerplate: No need to manage state or visibility flags manually.

---

📦 Installation

Add the dependency to your commonMain source set in build.gradle.kts:

sourceSets {
    commonMain.dependencies {
        implementation("io.github.kratos1996:popbox:1.0.1")
    }
}

---

🛠️ Setup

1. Configure Signing (for publishing): If you plan to publish to Maven Central, create a local.properties file based on local.properties.template and fill in your GPG signing keys and Maven Central credentials.

2. Initialize PopBoxHost: Wrap your application's root content with PopBoxHost. This should typically be done in your top-level Composable (e.g., inside your MaterialTheme).

@Composable
fun App() {
    MaterialTheme {
        PopBoxHost {
            // Your app content goes here
            MainScreen()
        }
    }
}

---

💡 Usage

Access the LocalPopBoxController to show or dismiss dialogs. The content lambda provides a dismiss callback.

1. Basic PopBox

val controller = LocalPopBoxController.current

Button(onClick = {
    controller.show { dismiss ->
        Column(Modifier.padding(16.dp)) {
            Text("Simple PopBox")
            Button(onClick = dismiss) { Text("Close") }
        }
    }
}) {
    Text("Show PopBox")
}

2. Customizing Appearance

Use PopBoxParams to tweak the behavior and look:

controller.show(
    params = PopBoxParams(
        disableOuterTap = true, // Force user to use close button
        containerColor = Color.White,
        shape = RoundedCornerShape(8.dp),
        contentPadding = 32.dp
    )
) { dismiss ->
    Text("Sticky PopBox", Modifier.padding(16.dp))
    Button(onClick = dismiss) { Text("I understand") }
}

---

⚙️ API Reference: PopBoxParams

Parameter	Type	Default	Description
disableOuterTap	Boolean	false	If true, clicking outside or back press won't dismiss the dialog.
shape	Shape	RoundedCornerShape(16.dp)	The shape of the dialog container.
containerColor	Color?	null	Background color of the dialog (defaults to MaterialTheme white).
horizontalPadding	Dp	24.dp	Padding from screen edges.
contentPadding	Dp	20.dp	Internal padding for content.
onDismissRequest	(() -> Unit)?	null	Callback triggered when the dialog is dismissed.

---

🌍 Platform Support

Platform	Support
Android	✅
iOS	✅
Desktop (JVM)	✅
Web (Wasm/JS)	✅

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an issue for bugs and feature requests.

📄 License

Copyright 2026 Ishant Sharma

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