What causes "global document not set" in yewstack/yew?

Use `gloo::utils::document()` to obtain the live global document

global document not set

Error message

global document not set

What it means

This panic is `Document::new().expect("global document not set")` in Yew 0.23's web-sys guide. `web_sys::Document::new()` calls the JS `Document` constructor; it is not the global-document accessor the message implies. In DOM-less environments (workers, SSR) or engines without the constructor it throws, and wasm-bindgen converts the thrown value into the `Err` that this expect panics on. Where the constructor works it yields a new empty document, which then makes the following `get_element_by_id("mousemoveme")` expect (error 76) inevitable.

Source

Thrown at website/versioned_docs/version-0.23/concepts/basic-web-technologies/web-sys.mdx:182

```rust ,no_run
use wasm_bindgen::{prelude::Closure, JsCast};
use web_sys::{console, Document, HtmlElement, MouseEvent};

let mousemove = Closure::<dyn Fn(MouseEvent)>::wrap(Box::new(|e: MouseEvent| {
    let rect = e
        .target()
        .expect("mouse event doesn't have a target")
        .dyn_into::<HtmlElement>()
        .expect("event target should be of type HtmlElement")
        .get_bounding_client_rect();
    let x = (e.client_x() as f64) - rect.left();
    let y = (e.client_y() as f64) - rect.top();
    console::log_1(&format!("Left? : {} ; Top? : {}", x, y).into());
}));

Document::new()
    .expect("global document not set")
    .get_element_by_id("mousemoveme")
    .expect("element with id `mousemoveme` not present")
    .unchecked_into::<HtmlElement>()
    .set_onmousemove(mousemove.as_ref().dyn_ref());

// we now need to save the `mousemove` Closure so that when
// this event fires the closure is still in memory.
```

This version is much more verbose, but you will probably notice part of that is because of failure
types reminding us that some of these function calls have invariants that must be held, or otherwise will
cause a panic in Rust. Another part of the verbosity is the calls to `JsCast` to cast into
different types so that you can call its specific methods.

### Yew example

In Yew you will mostly be creating [`Callback`](concepts/function-components/callbacks.mdx)s to use in the
[`html!`](concepts/html/introduction.mdx) macro so the example is going to use this approach instead of completely copying

View on GitHub (pinned to 0e4a05472f)

Solutions

Use `gloo::utils::document()` to obtain the live global document
Or `web_sys::window().and_then(|w| w.document())` with explicit expects on window/document presence
Keep DOM access out of worker/SSR code paths

Example fix

// before
Document::new()
    .expect("global document not set")
    .get_element_by_id("mousemoveme")

// after
gloo::utils::document().get_element_by_id("mousemoveme")
// equivalent explicit form:
// web_sys::window().and_then(|w| w.document()).expect("no global document")

Defensive patterns

Strategy: validation

Validate before calling

fn global_document() -> Option<web_sys::Document> {
    web_sys::window().and_then(|w| w.document())
}

if global_document().is_none() {
    gloo::console::warn("no global document — skipping DOM setup");
}

Prevention

Document::new() creates a new empty document — never use it to reach page elements
Use gloo::utils::document() as the single global-document accessor
Keep DOM code out of worker and SSR paths via cfg/feature gates
Codematch for Document::new() in review — it is almost always a copy-paste from this guide

When it happens

Trigger: Executing the example code where the JS `Document` constructor throws or no DOM exists (web worker, SSR, Node test without DOM polyfill); copying the guide line verbatim instead of using a global-document accessor.

Common situations: Copy-pasting the web-sys.mdx example into a Yew 0.23 app that already ships gloo; unit tests under `wasm-bindgen-test` in Node; Trunk SSR builds.

Related errors

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