What causes "Expected to find a #modal_host element" in yewstack/yew?

Add ` ` to `index.html` (the static page shell Trunk serves)

Expected to find a #modal_host element

Error message

Expected to find a #modal_host element

What it means

This panic is the `.expect()` after `gloo::utils::document().get_element_by_id("modal_host")` in Yew 0.22's portals guide. `get_element_by_id` returns `Option<Element>` and returns None when the current page markup contains no element with that exact id. The guide requires your static `index.html` to contain the portal destination `<div id="modal_host"></div>` before any `<Modal>` renders into it; the panic means that host element does not exist in the document the code ran against.

Source

Thrown at website/versioned_docs/version-0.22/advanced-topics/portals.mdx:38

Note that `yew::create_portal` is a low-level building block. Libraries should use it to implement
higher-level APIs which can then be consumed by applications. For example, here is a
simple modal dialogue that renders its `children` into an element outside `yew`'s control,
identified by the `id="modal_host"`.

```rust
use yew::prelude::*;

#[derive(Properties, PartialEq)]
pub struct ModalProps {
    #[prop_or_default]
    pub children: Html,
}

#[component]
fn Modal(props: &ModalProps) -> Html {
    let modal_host = gloo::utils::document()
        .get_element_by_id("modal_host")
        .expect("Expected to find a #modal_host element");

    create_portal(
        props.children.clone(),
        modal_host.into(),
    )
}
```

## Event handling

Events emitted on elements inside portals follow the virtual DOM when bubbling up. That is,
if a portal is rendered as the child of an element, then an event listener on that element
will catch events dispatched from inside the portal, even if the portal renders its contents
in an unrelated location in the actual DOM.

This allows developers to be oblivious of whether a component they consume, is implemented with
or without portals. Events fired on its children will bubble up regardless.

View on GitHub (pinned to 0e4a05472f)

Solutions

Add `<div id="modal_host"></div>` to `index.html` (the static page shell Trunk serves)
Verify the exact id spelling and casing in both `index.html` and the `get_element_by_id` call
If the host may legitimately be absent, replace the expect with `if let Some(host)` and render nothing or a placeholder instead of creating the portal
Make sure the component creating the portal mounts after the DOM is parsed (module scripts / `defer` guarantee this)

Example fix

// index.html — add the host before the app mounts
// <body>
//   <div id="modal_host"></div>
//   ...
// </body>

// component — before
let modal_host = gloo::utils::document()
    .get_element_by_id("modal_host")
    .expect("Expected to find a #modal_host element");

// component — after (fail soft when the host is missing)
if let Some(modal_host) = gloo::utils::document().get_element_by_id("modal_host") {
    create_portal(props.children.clone(), modal_host.into())
} else {
    html! { <p>{"modal host #modal_host missing"}</p> }
}

Defensive patterns

Strategy: validation

Validate before calling

fn find_portal_host(id: &str) -> Option<web_sys::Element> {
    gloo::utils::document().get_element_by_id(id)
}

// before rendering the Modal component
if find_portal_host("modal_host").is_none() {
    gloo::console::warn("#modal_host missing in index.html — portal will be skipped");
}

Prevention

Declare every required portal host div in index.html next to the app mount point
Keep DOM element ids in one constants module and reuse them in Rust and HTML
Add a startup or e2e assertion that all portal host ids resolve before first render
Ship a helper that returns Option and renders a placeholder instead of calling expect

When it happens

Trigger: Rendering the `<Modal>` component when `index.html` has no element with `id="modal_host"`; the id is misspelled or differently cased (`Modal_host`, `modalhost`); the app shell HTML is produced by a template that omits the host div; or the lookup ran against a document that never contains it.

Common situations: Copy-pasting the portals example without editing `index.html`; switching Trunk templates or app shells; `wasm-bindgen-test` suites that render the component into a scratch document; SSR passes where the host div is only added client-side after the first render.

Related errors

AI-assisted analysis of yewstack/yew@0e4a05472f (2026-08-22). Data as JSON: /api/errors/7d07671a1884b867. Report an issue: GitHub.