We're dsplce.co, check out our work on github.com/dsplce-co 🖤

dioxus-modal

Modal composable for Dioxus — A minimal and type-safe framework for modals in Dioxus applications.

⸻

🖤 Features

✅ Type-safe modal system with generics ✅ Pass additional context to your modals ✅ Close your modals from anywhere with a global fn ✅ ARIA-compliant ✅ Esc key handling ✅ Portal-style rendering with proper z-index ✅ Proc macro for modal component creation ✅ Zero external CSS dependencies

⸻

📦 Installation

Add to your Cargo.toml:

[dependencies]
dioxus-modal = "0.1.2"

This crate requires Rust 2024 edition and is compatible with Dioxus 0.6.

⸻

🧪 Usage

1. Set up modal collector

Add the ModalCollector component to your app to enable rendering modals.

For client-side rendered (CSR) applications, you may need to ensure the collector is only rendered after hydration:

use dioxus::prelude::*;
use dioxus_modal::prelude::*;

#[component]
fn App() -> Element {
    let mut csr = use_signal(|| false);

    use_effect(move || {
        if !csr() {
            csr.set(true);
        }
    });

    rsx! {
        if csr() {
            Router::<Route> {}
            ModalCollector {}
        }
    }
}

2. Create modal component

Imagine in your application there is a user list view, and you want to add the functionality to delete a user to it. You decide a confirmation dialog would come in handy.

In dioxus-modal, your modal component needs to adhere to the following signature:

#[modal]
pub fn ConfirmationModal(input: Input, ctx: Context, close: fn()) -> Element;

Where:

Input is dynamic data typically not known until the modal's opening is triggered (in our example it would be the user to delete). Should satisfy 'static
Context is something constant, passed to the modal on registration and thus not changeable (eg. a function responsible for user deletion). Should satisfy 'static + Clone

Let's implement the confirmation dialog:

use dioxus_modal::prelude::*;

#[modal]
pub fn ConfirmationModal(user: User, delete_callback: fn(String), close: fn()) -> Element {
    rsx! {
        div {
            class: "confirmation-modal",
            h2 { "Confirm Action" }
            p { "Are you sure you want to delete {user.name}?" }

            div {
                class: "confirmation-modal__actions",
                button {
                    onclick: move |_| close(),
                    "Cancel"
                }
                button {
                    onclick: move |_| {
                        delete_callback(user.id.clone());
                        close();
                    },
                    "Confirm"
                }
            }
        }
    }
}

3. Use the modal

Now that you've defined the confirmation modal, let's call it using the use_modal! macro:

use dioxus::{logger::tracing, prelude::*};
use dioxus_modal::prelude::*;

#[derive(Clone, PartialEq)]
struct User {
    id: String,
    name: String,
}

#[component]
fn UsersView(users: Vec<User>) -> Element {
    let delete_user = move |id: String| {
        tracing::info!("Deleting user with id {id}");
    };

    // Registers the modal
    let modal = use_modal!(ConfirmationModal, delete_user);

    let on_delete = EventHandler::new(move |user: User| {
        modal.open(user.clone());
    });

    rsx! {
        // ❗ Notice the `ConfirmationModal` is not mounted directly
        // anywhere — it is the `ModalCollector`'s job to render modals
        ul {
            for user in users {
                li {
                    key: "{user.id}",
                    "{user.name}"
                    button {
                        onclick: move |_| on_delete.call(user.clone()),
                        "Delete"
                    }
                }
            }
        }
    }
}

⸻

📐 API Reference

`ModalCollector`

Singleton component that manages modal state and rendering.

`#[modal]`

Proc macro that helps the ModalCollector render your modals.

`use_modal!`

Creates a typed modal controller:

// Without context
let modal = use_modal!(ModalComponent);

// With context
let modal = use_modal!(ModalComponent, context);

Returns a modal struct with the methods:

open(args) - Opens the modal with provided arguments
close() - Closes the modal

`close`

Close the modal from anywhere in your application:

dioxus_modal::close();

Defining a modal

With both context and input:

#[modal]
pub fn ModalComponent(input: Input, ctx: Context, close: fn()) -> Element {
    rsx! {
        // ...
    }
}

let modal = use_modal!(ModalComponent, context);
modal.open(input)

Skipping context:

#[modal]
pub fn ModalComponent(input: Input, ctx: (), close: fn()) -> Element {
    rsx! {
        // ...
    }
}

let modal = use_modal!(ModalComponent);
modal.open(input)

Skipping input:

#[modal]
pub fn ModalComponent(input: (), ctx: Context, close: fn()) -> Element {
    rsx! {
        // ...
    }
}

let modal = use_modal!(ModalComponent, context);
modal.open(())

Modal Features

Accessibility: Proper ARIA attributes (role="dialog", aria-modal)
Keyboard Navigation: Esc key closes modal out of the box
Global State: Modals have a single place to render, and there is always one modal visible at a time (why would you want to show more than one modal at a time? 🤨)
Overlay: Semi-transparent backdrop with proper positioning
Responsive: Full viewport coverage with centered content
Transitions: Built-in smooth enter/leave modal transitions

⸻

📁 Repo & Contributions

📦 Crate: crates.io/crates/dioxus-modal 🛠️ Repo: github.com/dsplce-co/dioxus-modal

Contributions, issues, ideas? Hit us up 🖤

⸻

🔒 License

MIT or Apache-2.0, at your option.

⸻

dioxus-modal 0.1.2