Manipulating the DOM from Rust with web-sys

24 min read

A WebAssembly module compiled from Rust has no document, no querySelector, and no event system of its own — those all live in JavaScript. The web-sys crate gives Rust a typed view of every browser API, so you can grab the document, query and create elements, set text and attributes, and attach event listeners from Rust while the browser does the actual rendering. This page is the practical, DOM-focused companion to the boundary mechanics in wasm-bindgen.md.

Quick Overview

web-sys is a single, enormous crate that mirrors the entire Web IDL surface — Window, Document, Element, HtmlInputElement, Event, and thousands more — as Rust types with methods. Because it is so large, every API is hidden behind a Cargo feature flag, and you enable only the types you touch, which keeps compile times and bundle size sane. For a TypeScript developer the mental model is: web-sys is the lib.dom.d.ts of the Rust world, except the “types” are real, callable wrappers over the JavaScript glue rather than erased declarations. The big adjustments are that DOM calls return Result/Option instead of throwing or returning null, and that the DOM’s runtime class hierarchy (Node → Element → HtmlInputElement) becomes an explicit downcast (dyn_into) in Rust rather than the implicit narrowing TypeScript does with as.

TypeScript/JavaScript Example

Here is a small, realistic to-do widget written the way a front-end engineer would: grab elements, listen for the Enter key, append a list item, and toggle items done by clicking them.

1
// todo.ts — runs in the browser's main thread
2
class TodoApp {
3
  private items: string[] = [];
4

5
  constructor(private root: HTMLElement) {
6
    const input = document.createElement("input");
7
    input.placeholder = "What needs doing?";
8
    input.id = "new-todo";
9

10
    const list = document.createElement("ul");
11
    list.id = "todo-list";
12

13
    this.root.append(input, list);
14

15
    // Add an item when the user presses Enter.
16
    input.addEventListener("keydown", (ev: KeyboardEvent) => {
17
      if (ev.key !== "Enter") return;
18
      const text = input.value.trim();
19
      if (!text) return;
20
      this.items.push(text);
21

22
      const li = document.createElement("li");
23
      li.textContent = text;
24
      list.append(li);
25
      input.value = "";
26
    });
27

28
    // Event delegation: one listener on the list toggles the clicked item.
29
    list.addEventListener("click", (ev: MouseEvent) => {
30
      const li = (ev.target as HTMLElement).closest("li");
31
      li?.classList.toggle("done");
32
    });
33
  }
34

35
  get count(): number {
36
    return this.items.length;
37
  }
38
}
39

40
const app = new TodoApp(document.querySelector<HTMLElement>("#root")!);

The logic is so routine it is almost invisible to a JavaScript developer. To check the exact runtime behavior of the bookkeeping — trimming, counting, clearing — the same model run under Node v22 prints:

1
added "buy milk" (now 1 items)
2
added "write Rust guide" (now 2 items)
3
[ 'buy milk', 'write Rust guide' ]
4
cleared
5
0

Four operations matter, because each maps onto a web-sys idiom: getting a typed element (querySelector<HTMLElement>), creating and appending nodes (createElement / append), reading a typed property (input.value), and registering event listeners (addEventListener). We rebuild all four in Rust below.

Rust Equivalent

Create a library crate that builds a cdylib (see wasm-pack.md), then add the boundary crates. The current stable toolchain is Rust 1.96.0 on the 2024 edition, and cargo new selects that edition automatically:

1
cargo new --lib todo-dom
2
cd todo-dom
3
cargo add wasm-bindgen js-sys
4
cargo add web-sys --features "Window,Document,Element,HtmlElement,HtmlInputElement,Node,NodeList,Event,EventTarget,KeyboardEvent,DomTokenList,console"

That last command is the part newcomers miss: web-sys does nothing until you opt into the specific types via features. The resulting Cargo.toml:

1
[package]
2
name = "todo-dom"
3
version = "0.1.0"
4
edition = "2024"
5

6
[lib]
7
crate-type = ["cdylib", "rlib"]
8

9
[dependencies]
10
js-sys = "0.3.99"
11
wasm-bindgen = "0.2.122"
12
web-sys = { version = "0.3.99", features = [
13
    "Window", "Document", "Element", "HtmlElement", "HtmlInputElement",
14
    "Node", "NodeList", "Event", "EventTarget", "KeyboardEvent",
15
    "DomTokenList", "console",
16
] }

Now the four core operations in src/lib.rs. Each is a free function here for clarity; the Real-World Example assembles them into a stateful component.

1
use wasm_bindgen::prelude::*;
2
use web_sys::{HtmlInputElement, window};
3

4
// 1. Get the document, query an element, set its text content.
5
#[wasm_bindgen]
6
pub fn render_greeting(name: &str) -> Result<(), JsValue> {
7
    // window() returns Option<Window> — there is no implicit global in Rust.
8
    let window = window().expect("no global `window` exists");
9
    let document = window.document().expect("should have a document on window");
10

11
    // query_selector returns Result<Option<Element>, JsValue>:
12
    // the Result is the "the selector was invalid" channel, the Option is "not found".
13
    let heading = document
14
        .query_selector("#greeting")?
15
        .expect("no #greeting element");
16

17
    // textContent is set via a method, and it takes Option<&str> (None clears it).
18
    heading.set_text_content(Some(&format!("Hello, {name}!")));
19
    Ok(())
20
}
21

22
// 2. Create an element, set attributes/classes, append it to a parent.
23
#[wasm_bindgen]
24
pub fn add_todo(text: &str) -> Result<(), JsValue> {
25
    let document = window().unwrap().document().unwrap();
26

27
    let li = document.create_element("li")?; // Result<Element, JsValue>
28
    li.set_text_content(Some(text));
29
    li.set_class_name("todo-item");
30
    li.set_attribute("data-done", "false")?;
31

32
    let list = document
33
        .get_element_by_id("todo-list")
34
        .expect("#todo-list missing");
35
    list.append_child(&li)?; // Node::append_child, returns Result<Node, JsValue>
36
    Ok(())
37
}
38

39
// 3. Read a typed property — requires downcasting Element to HtmlInputElement.
40
#[wasm_bindgen]
41
pub fn read_input_value(selector: &str) -> Result<String, JsValue> {
42
    let document = window().unwrap().document().unwrap();
43
    let el = document
44
        .query_selector(selector)?
45
        .ok_or_else(|| JsValue::from_str("element not found"))?;
46

47
    // .value() lives on HtmlInputElement, not the generic Element — narrow first.
48
    let input: HtmlInputElement = el
49
        .dyn_into::<HtmlInputElement>()
50
        .map_err(|_| JsValue::from_str("not an <input>"))?;
51

52
    Ok(input.value())
53
}
54

55
// 4. Register a click listener via a Closure, kept alive with forget().
56
#[wasm_bindgen]
57
pub fn wire_up_button() -> Result<(), JsValue> {
58
    let document = window().unwrap().document().unwrap();
59
    let button = document
60
        .get_element_by_id("click-me")
61
        .expect("#click-me missing");
62

63
    let count = std::rc::Rc::new(std::cell::Cell::new(0u32));
64
    let count_for_cb = count.clone();
65

66
    // The closure receives the DOM Event. Shared state goes through Rc<Cell>.
67
    let on_click = Closure::<dyn FnMut(web_sys::Event)>::new(move |_event: web_sys::Event| {
68
        count_for_cb.set(count_for_cb.get() + 1);
69
        web_sys::console::log_1(&format!("clicked {} times", count_for_cb.get()).into());
70
    });
71

72
    button.add_event_listener_with_callback("click", on_click.as_ref().unchecked_ref())?;
73

74
    // forget() leaks the Closure for the program's lifetime so the listener
75
    // keeps firing. Store it in a struct instead when you need to remove it.
76
    on_click.forget();
77
    Ok(())
78
}

Building against the browser target compiles cleanly:

1
$ cargo build --target wasm32-unknown-unknown
2
   Compiling wasm-bindgen v0.2.122
3
   Compiling js-sys v0.3.99
4
   Compiling web-sys v0.3.99
5
   Compiling todo-dom v0.1.0 (/.../todo-dom)
6
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1m 00s

Note: Plain cargo build type-checks against your host platform; only --target wasm32-unknown-unknown emits a real .wasm. In practice you run wasm-pack build (wasm-pack.md), which compiles and runs the wasm-bindgen CLI to produce the JavaScript glue in one step.

Detailed Explanation

Getting the document: no ambient globals

In JavaScript, document and window are ambient — they are just there. In Rust there is no global state you can dereference; you call web_sys::window(), which returns Option<Window> (None when there is no global window, e.g. inside a Web Worker), and then window.document(), which is also an Option. The idiomatic pattern is:

1
use web_sys::window;
2

3
let document = window()
4
    .expect("should run in a browser context")
5
    .document()
6
    .expect("document should exist");

.expect() is fine for a hard precondition like “we are in a browser.” In production code you would return Result<_, JsValue> and propagate with ?, as the snippets above do, so a missing document becomes a thrown JavaScript exception rather than a panic that aborts the whole module. The distinction between Option (covered in Section 08) and Result is load-bearing here: web-sys uses Option for “the thing might not be present” and Result<_, JsValue> for “the underlying JavaScript call can throw.”

Why DOM calls return `Result` and `Option`

document.querySelector("#x") in JavaScript returns Element | null, and it throws a SyntaxError if the selector string is malformed. web-sys models both outcomes honestly in the type:

1
query_selector(&self, selectors: &str) -> Result<Option<Element>, JsValue>

The Result is the throw channel (invalid selector); the inner Option is the null channel (valid selector, no match). This is the recurring shape across web-sys: anything that can throw returns Result<_, JsValue>, and anything nullable returns Option. A TypeScript developer used to el!.textContent (a non-null assertion) writes el.expect(...) or el.ok_or_else(...)? instead — the compiler will not let you forget the absent case, which is the whole point.

The DOM class hierarchy and downcasting

The browser’s DOM is an inheritance tree: EventTarget → Node → Element → HTMLElement → HTMLInputElement, and so on. TypeScript reflects this with lib.dom.d.ts interfaces and lets you narrow with as or type guards — a compile-time-only operation that does nothing at runtime. web-sys reflects the same tree with concrete Rust types, but a generic Element does not expose .value() — that method only exists on HtmlInputElement. To reach it you perform a checked downcast with dyn_into:

1
use wasm_bindgen::JsCast; // brings dyn_into / dyn_ref into scope (re-exported by the prelude)
2
use web_sys::HtmlInputElement;
3

4
let input: HtmlInputElement = element
5
    .dyn_into::<HtmlInputElement>()       // Result<HtmlInputElement, Element>
6
    .map_err(|_| JsValue::from_str("not an <input>"))?;

This is the single biggest difference from TypeScript narrowing. element as HTMLInputElement in TypeScript is erased — if the element is not an input, you get undefined when you read .value and a silent bug. dyn_into performs a real runtime instanceof-style check and returns Err(original) when the cast fails, so a wrong assumption surfaces immediately. Use dyn_ref::<T>() when you only need a borrowed &T without consuming the value, and dyn_into::<T>() when you want to take ownership. The JsCast trait that provides them is part of wasm_bindgen::prelude, so use wasm_bindgen::prelude::*; brings it in.

Creating, configuring, and inserting nodes

The node-construction APIs map almost one-to-one, just renamed to Rust’s snake_case and returning Result:

JavaScript	`web-sys` (Rust)
`document.createElement("li")`	`document.create_element("li")?`
`el.textContent = "x"`	`el.set_text_content(Some("x"))`
`el.className = "c"`	`el.set_class_name("c")`
`el.setAttribute("k", "v")`	`el.set_attribute("k", "v")?`
`el.id = "x"`	`el.set_id("x")`
`parent.appendChild(child)`	`parent.append_child(&child)?`
`el.remove()`	`el.remove()`

append_child lives on Node (every Element is a Node, so the method is available via deref). It borrows the child (&child) because the DOM takes a reference into its own tree; ownership of the Rust Element handle stays with you. Two convenient shortcuts: set_text_content(Some("")) empties an element’s children in one call (the fast way to clear a list), and set_inner_html exists too — but treat it exactly as you would in JavaScript, as an XSS hazard unless the content is trusted or sanitized.

Event listeners: closures that must outlive the call

This is where Rust’s ownership model meets the DOM head-on. addEventListener needs a callable function and the browser keeps calling it later, long after your Rust function has returned. A Rust closure cannot be handed to JavaScript directly; you wrap it in a wasm_bindgen::closure::Closure, which allocates a JS function that trampolines back into Rust. The catch is lifetime:

1
let on_click = Closure::<dyn FnMut(web_sys::Event)>::new(move |event: web_sys::Event| {
2
    // ... handler body ...
3
});
4
button.add_event_listener_with_callback("click", on_click.as_ref().unchecked_ref())?;

add_event_listener_with_callback expects a &js_sys::Function. on_click.as_ref() yields a &JsValue, and .unchecked_ref() reinterprets it as the &Function the API wants. (This is the one place an unchecked cast is idiomatic, because we know a Closure is a function.)
The Closure is valid only while it is alive in Rust. If it is dropped, the JavaScript function dangles and the next click throws closure invoked recursively or after being dropped. You therefore must either store it somewhere that outlives the listener, or call .forget() to leak it for the program’s lifetime.
Closure::<dyn FnMut(...)>::new is for repeated calls (events, intervals); Closure::once frees itself after a single call.

.forget() is the right tool for a listener that lives as long as the page (a global click handler). For a listener you intend to remove later, you must keep the Closure in a field so you can pass the same function reference to remove_event_listener_with_callback. The Real-World Example stores its closure; the deeper rules are in wasm-bindgen.md.

Mutable shared state without `&mut`

The click handler increments a counter, but the closure is move and outlives the function — there is no &mut you could capture safely. Single-threaded WASM in the browser means the answer is Rc<Cell<T>> (or Rc<RefCell<T>> for non-Copy data), the single-threaded interior-mutability pattern from Section 10. Rc gives shared ownership so both the closure and the surrounding code hold the value; Cell/RefCell provide the mutation. You do not reach for Arc/Mutex here — there are no threads to guard against, and the atomics would be wasted overhead.

Key Differences

Concept	TypeScript/JavaScript	Rust + `web-sys`
Access to DOM types	Ambient (`lib.dom.d.ts`), always available	Behind per-type Cargo features you must enable
`document` / `window`	Ambient globals	`web_sys::window()` → `Option<Window>` → `.document()` → `Option<Document>`
`querySelector` result	`Element \| null`, throws on bad selector	`Result<Option<Element>, JsValue>`
Narrowing a node type	`el as HTMLInputElement` (erased, no-op at runtime)	`el.dyn_into::<HtmlInputElement>()` (real runtime check, returns `Result`)
Setting properties	`el.textContent = x` (assignment)	`el.set_text_content(Some(x))` (method, `Option<&str>`)
Event handler	Any function; GC’d automatically	`Closure<dyn FnMut(Event)>`; you manage its lifetime
Mutable captured state	Plain closure over a variable	`Rc<Cell<T>>` / `Rc<RefCell<T>>`
Errors	Exceptions you may ignore	`Result<_, JsValue>` you must handle or `?`-propagate

The conceptual core is the inversion of nullability and error handling. JavaScript lets you write document.querySelector("#x").textContent = "hi" and only discover at runtime that querySelector returned null. Rust forces every “might be absent” and “might throw” into the type, so the same line becomes several explicit steps — more verbose, but the class of “cannot read properties of null” runtime error simply cannot occur. The other pillar is that the DOM’s runtime polymorphism becomes explicit, checked downcasts, replacing TypeScript’s erased as.

Note: web-sys is auto-generated from the browser’s Web IDL, so its coverage is essentially complete and its naming is mechanical: getElementById → get_element_by_id, addEventListener → add_event_listener_with_callback (the suffix names the argument variant). When you cannot find a method, search docs.rs/web-sys for the type and remember the snake_case + with_* convention.

Common Pitfalls

Pitfall 1: Forgetting the Cargo feature flag

Every web-sys type is gated behind a feature. If you use web_sys::HtmlInputElement without enabling the HtmlInputElement feature, the type simply does not exist in the crate. This is the most common first error, and the message is initially confusing because it looks like a typo:

1
use wasm_bindgen::prelude::*;
2
use web_sys::{HtmlInputElement, window}; // does not compile if "HtmlInputElement" feature is off
3

4
#[wasm_bindgen]
5
pub fn read_value(selector: &str) -> Result<String, JsValue> {
6
    let document = window().unwrap().document().unwrap();
7
    let el = document.query_selector(selector)?.unwrap();
8
    let input: HtmlInputElement = el.dyn_into().map_err(|_| JsValue::from_str("nope"))?;
9
    Ok(input.value())
10
}

Real compiler output:

1
error[E0432]: unresolved import `web_sys::HtmlInputElement`
2
 --> src/lib.rs:2:15
3
  |
4
2 | use web_sys::{HtmlInputElement, window};
5
  |               ^^^^^^^^^^^^^^^^ no `HtmlInputElement` in the root
6

7
For more information about this error, try `rustc --explain E0432`.

Fix: add the feature — cargo add web-sys --features HtmlInputElement — and note that methods are gated too. Calling el.class_list() needs the DomTokenList feature even though class_list is a method on Element; el.style() needs CssStyleDeclaration. When a method “doesn’t exist,” check its return type’s feature, not just the receiver’s.

Pitfall 2: Calling a subtype method on a generic `Element`

Because query_selector returns the base Element, calling an HtmlInputElement method on it without downcasting fails. This trips up TypeScript developers who are used to querySelector<HTMLInputElement>(...) baking the narrow type into the call:

1
use wasm_bindgen::prelude::*;
2
use web_sys::window;
3

4
#[wasm_bindgen]
5
pub fn read_value(selector: &str) -> Result<String, JsValue> {
6
    let document = window().unwrap().document().unwrap();
7
    let el = document.query_selector(selector)?.unwrap();
8
    Ok(el.value()) // does not compile (error[E0599]): value() is not on Element
9
}

Real compiler output:

1
error[E0599]: no method named `value` found for struct `web_sys::Element` in the current scope
2
 --> src/lib.rs:9:11
3
  |
4
9 |     Ok(el.value())
5
  |           ^^^^^
6
  |
7
help: there is a method `value_of` with a similar name
8
  |
9
9 |     Ok(el.value_of())
10
  |                +++
11

12
For more information about this error, try `rustc --explain E0599`.

Warning: Do not take the compiler’s value_of suggestion — value_of is the generic Object.valueOf() from js-sys, not an input’s .value. This is a case where the “did you mean” hint is misleading. The real fix is to downcast: let input: HtmlInputElement = el.dyn_into().map_err(...)?; input.value().

Pitfall 3: The dropped-closure runtime crash

This one compiles and then fails at runtime, which makes it the nastiest. If you create a Closure, register it, and let it fall out of scope, the JS function is freed while the DOM still references it:

1
// Compiles fine, breaks at the first click.
2
let cb = Closure::<dyn FnMut(web_sys::Event)>::new(move |_| { /* ... */ });
3
button.add_event_listener_with_callback("click", cb.as_ref().unchecked_ref())?;
4
// `cb` is dropped here at end of scope; the listener now dangles.

There is no E-code because Rust’s type system cannot see across the boundary into the DOM’s reference. The browser console throws closure invoked recursively or after being dropped on the first click. Fix: either cb.forget() for a page-lifetime listener, or store cb in a struct field that outlives the element (as the Real-World Example does). This is the DOM-flavored version of the closure-lifetime rule covered in wasm-bindgen.md.

Pitfall 4: Treating `query_selector`’s `Option` as the error

query_selector returns Result<Option<Element>, JsValue>. Newcomers sometimes ?-propagate and then .unwrap() the Option, conflating “not found” with “error.” A missing element is not an exception — it is a None you should handle deliberately (return a typed error, create the element, or skip). Use .ok_or_else(|| JsValue::from_str("..."))? to turn “not found” into a meaningful thrown error, rather than a bare .unwrap() that panics with called Option::unwrap() on a None value and aborts the module.

Pitfall 5: Reaching for `&mut self` in a handler

Trying to capture &mut something in an event closure runs into the borrow checker because the closure is 'static (it outlives the current frame) and may be invoked re-entrantly. The fix is not unsafe or a raw pointer — it is Rc<RefCell<T>>. Capture an Rc clone, and borrow_mut() inside the handler. Forgetting and trying to share a plain &mut produces a lifetime error pointing at the closure’s 'static requirement; the structural fix is interior mutability (Section 10).

Best Practices

Enable only the features you use. Each web-sys feature you add increases compile time. Keep the features = [...] list tight and let the compiler’s “unresolved import” errors tell you what to add, rather than enabling everything.
Return Result<_, JsValue> from exported DOM functions. Propagate with ? so a missing element or a throwing call surfaces as a JavaScript exception the caller can try/catch, instead of a panic that aborts the whole WASM instance.
Prefer dyn_into / dyn_ref over unchecked_into. The checked casts catch a wrong assumption at the moment it happens. Reserve unchecked_ref/unchecked_into for the narrow case where you know the type — chiefly handing a Closure to add_event_listener_with_callback.
Store long-lived closures; forget() only page-lifetime ones. If a listener must be removable, keep its Closure in a struct field and pair add_event_listener_with_callback with remove_event_listener_with_callback. Use .forget() deliberately and comment why you are leaking.
Batch DOM writes. Crossing into the DOM is a boundary call; build a subtree (or an HTML string) and append it once rather than touching the live tree in a tight loop. The boundary economics are in performance.md.
Use Rc<RefCell<T>>, never Arc<Mutex<T>>, for shared UI state. Browser WASM is single-threaded; the atomic machinery buys you nothing and costs size and speed.
Install console_error_panic_hook in debug builds so a Rust panic shows a readable stack trace in the console instead of unreachable executed. See first-wasm.md.
Reach for a framework when the DOM logic grows. Hand-written web-sys is perfect for a focused widget or a fast kernel that touches a few nodes. For a whole reactive UI, the imperative create/append/listen code becomes a maintenance burden — that is what Yew and Leptos solve (yew-leptos.md).

Real-World Example

A self-contained to-do component that owns its state and keeps its event closure alive — the production-flavored version of the TypeScript class at the top. It mounts into #root, adds an item on Enter, exposes a count getter to JavaScript, and can clear() itself. The whole module compiles cleanly against wasm32-unknown-unknown.

1
use std::cell::RefCell;
2
use std::rc::Rc;
3
use wasm_bindgen::prelude::*;
4
use web_sys::{Document, Element, HtmlInputElement, KeyboardEvent, window};
5

6
// Shared, mutable state. Browser WASM is single-threaded, so Rc<RefCell<_>>
7
// is the right shared-ownership tool — no Arc/Mutex.
8
#[derive(Default)]
9
struct State {
10
    items: Vec<String>,
11
}
12

13
#[wasm_bindgen]
14
pub struct TodoApp {
15
    document: Document,
16
    list: Element,
17
    state: Rc<RefCell<State>>,
18
    // The closure must outlive the listener, so the struct owns it.
19
    _on_keydown: Closure<dyn FnMut(KeyboardEvent)>,
20
}
21

22
#[wasm_bindgen]
23
impl TodoApp {
24
    /// Mount the app into `#root`, wiring the input's Enter key to add items.
25
    #[wasm_bindgen(constructor)]
26
    pub fn new() -> Result<TodoApp, JsValue> {
27
        let document = window()
28
            .ok_or_else(|| JsValue::from_str("no window"))?
29
            .document()
30
            .ok_or_else(|| JsValue::from_str("no document"))?;
31

32
        let root = document
33
            .get_element_by_id("root")
34
            .ok_or_else(|| JsValue::from_str("missing #root"))?;
35

36
        // Build the input and list once.
37
        let input: HtmlInputElement = document
38
            .create_element("input")?
39
            .dyn_into()
40
            .map_err(|_| JsValue::from_str("not an input"))?;
41
        input.set_attribute("placeholder", "What needs doing?")?;
42
        input.set_id("new-todo");
43

44
        let list = document.create_element("ul")?;
45
        list.set_id("todo-list");
46

47
        root.append_child(&input)?;
48
        root.append_child(&list)?;
49

50
        let state = Rc::new(RefCell::new(State::default()));
51

52
        // The handler captures clones of everything it needs to live on its own.
53
        let cb_document = document.clone();
54
        let cb_list = list.clone();
55
        let cb_state = Rc::clone(&state);
56
        let cb_input = input.clone();
57
        let on_keydown = Closure::<dyn FnMut(KeyboardEvent)>::new(move |ev: KeyboardEvent| {
58
            if ev.key() != "Enter" {
59
                return;
60
            }
61
            let text = cb_input.value();
62
            let trimmed = text.trim();
63
            if trimmed.is_empty() {
64
                return;
65
            }
66
            cb_state.borrow_mut().items.push(trimmed.to_string());
67

68
            // Render one <li> for the new item.
69
            if let Ok(li) = cb_document.create_element("li") {
70
                li.set_text_content(Some(trimmed));
71
                let _ = cb_list.append_child(&li);
72
            }
73
            cb_input.set_value("");
74
        });
75

76
        input.add_event_listener_with_callback("keydown", on_keydown.as_ref().unchecked_ref())?;
77

78
        Ok(TodoApp {
79
            document,
80
            list,
81
            state,
82
            _on_keydown: on_keydown,
83
        })
84
    }
85

86
    /// How many items are stored — exposed to JavaScript as a getter.
87
    #[wasm_bindgen(getter)]
88
    pub fn count(&self) -> usize {
89
        self.state.borrow().items.len()
90
    }
91

92
    /// Remove every rendered <li> and clear the backing state.
93
    pub fn clear(&self) -> Result<(), JsValue> {
94
        self.state.borrow_mut().items.clear();
95
        // set_text_content(Some("")) empties a node's children in one call.
96
        self.list.set_text_content(Some(""));
97
        let _ = &self.document; // keep the field referenced
98
        Ok(())
99
    }
100
}

From TypeScript, the generated module is used like any class — the .d.ts that wasm-pack emits types count as a number getter and clear() as () => void:

1
import init, { TodoApp } from "./pkg/todo_dom.js";
2

3
await init(); // load + instantiate the .wasm once (see ./rust-from-js.md)
4

5
const app = new TodoApp(); // constructor mounts the UI into #root
6
// ...user types and presses Enter a few times...
7
console.log(app.count); // e.g. 3
8
app.clear();
9
app.free(); // opaque structs are not GC'd — free when done (see ./wasm-bindgen.md)

Three deliberate choices make this idiomatic. The _on_keydown field stores the Closure so the listener survives the constructor returning — drop it and the next keystroke throws. Rc<RefCell<State>> lets the closure and the struct’s methods share one mutable list without &mut gymnastics, and it is the single-threaded shared-state pattern rather than Arc<Mutex<_>>. And every fallible DOM call is ?-propagated into a Result<_, JsValue>, so a missing #root becomes a clean thrown exception rather than a panic that poisons the WASM instance.

Warning: Because TodoApp is a #[wasm_bindgen] struct, JavaScript holds an opaque pointer into WASM memory; it is not garbage collected. Call app.free() when the component is torn down (or use wasm-bindgen’s optional WeakRef finalization), or the instance — and its forgotten closure — leak for the page’s lifetime. See wasm-bindgen.md.

Exercises

Exercise 1: Toggle a CSS class

Difficulty: Beginner

Objective: Get the document, find an element, and mutate its classList — the most common DOM operation there is.

Instructions: Write a #[wasm_bindgen] function toggle_panel() -> Result<bool, JsValue> that finds the element with id panel, toggles the class "open" on it, and returns whether the class is now present. Enable the right features (Window, Document, Element, DomTokenList). Confirm it compiles against wasm32-unknown-unknown.

Solution

1
use wasm_bindgen::prelude::*;
2
use web_sys::window;
3

4
#[wasm_bindgen]
5
pub fn toggle_panel() -> Result<bool, JsValue> {
6
    let document = window().unwrap().document().unwrap();
7
    let panel = document
8
        .get_element_by_id("panel")
9
        .ok_or_else(|| JsValue::from_str("#panel not found"))?;
10

11
    // class_list() needs the "DomTokenList" feature; toggle() returns
12
    // Result<bool, JsValue> — true if the class is now present.
13
    let now_open = panel.class_list().toggle("open")?;
14
    Ok(now_open)
15
}

class_list().toggle("open") mirrors JavaScript’s el.classList.toggle("open") exactly, returning the new state. Note get_element_by_id returns Option<Element> (not a Result), because it cannot throw — only be absent — so we convert the None into a thrown error with ok_or_else. This compiles cleanly against the WASM target.

Exercise 2: Build a list in one append

Difficulty: Intermediate

Objective: Create a subtree off-DOM and attach it with a single boundary touch, contrasting with a chatty per-item loop.

Instructions: Write render_list(items: Vec<String>) -> Result<(), JsValue> that finds #list-root, builds a <ul> containing one <li> per item (with the item as text content), clears any previous content of #list-root, and appends the finished <ul>. Why is building the <ul> before appending it better than appending each <li> to a live list? Compile-verify.

Solution

1
use wasm_bindgen::prelude::*;
2
use web_sys::window;
3

4
#[wasm_bindgen]
5
pub fn render_list(items: Vec<String>) -> Result<(), JsValue> {
6
    let document = window().unwrap().document().unwrap();
7
    let container = document
8
        .get_element_by_id("list-root")
9
        .ok_or_else(|| JsValue::from_str("#list-root not found"))?;
10

11
    // Build the whole subtree off the live DOM first.
12
    let ul = document.create_element("ul")?;
13
    for item in &items {
14
        let li = document.create_element("li")?;
15
        li.set_text_content(Some(item));
16
        ul.append_child(&li)?;
17
    }
18

19
    // Clear old content, then attach the new subtree in one operation.
20
    container.set_text_content(Some(""));
21
    container.append_child(&ul)?;
22
    Ok(())
23
}

Vec<String> crosses the boundary as a string[] (wasm-bindgen handles the conversion). Building the <ul> in a detached node means the browser does layout/reflow work only once, when the finished subtree is inserted, rather than after every individual <li> append to a live, rendered list — the same reason JavaScript developers build a DocumentFragment or an HTML string before inserting. The function compiles against wasm32-unknown-unknown.

Exercise 3: Event delegation with one listener

Difficulty: Advanced

Objective: Attach a single listener to a parent and use event.target plus closest to handle clicks on dynamically-added children — the idiomatic way to avoid one listener per row.

Instructions: Write install_delegated_handler() -> Result<(), JsValue> that puts one "click" listener on #todo-list. In the handler, read event.target, downcast it to an Element, walk up to the nearest ancestor <li> with closest("li"), and toggle the class "done" on it. Keep the listener alive for the page’s lifetime. Explain why closest is needed rather than checking the target directly, and why the Closure is leaked. Compile-verify.

Solution

1
use wasm_bindgen::prelude::*;
2
use web_sys::{Element, Event, HtmlElement, window};
3

4
#[wasm_bindgen]
5
pub fn install_delegated_handler() -> Result<(), JsValue> {
6
    let document = window().unwrap().document().unwrap();
7
    let list = document
8
        .get_element_by_id("todo-list")
9
        .ok_or_else(|| JsValue::from_str("#todo-list not found"))?;
10

11
    let handler = Closure::<dyn FnMut(Event)>::new(move |ev: Event| {
12
        // event.target is Option<EventTarget>; narrow it to an Element.
13
        let Some(target) = ev.target() else { return };
14
        let Ok(el) = target.dyn_into::<Element>() else {
15
            return;
16
        };
17
        // closest() walks up to the nearest <li>, exactly like JS delegation.
18
        if let Ok(Some(li)) = el.closest("li") {
19
            if let Ok(li) = li.dyn_into::<HtmlElement>() {
20
                let _ = li.class_list().toggle("done");
21
            }
22
        }
23
    });
24

25
    list.add_event_listener_with_callback("click", handler.as_ref().unchecked_ref())?;
26
    // Page-lifetime listener: forget() leaks it deliberately so it keeps firing.
27
    handler.forget();
28
    Ok(())
29
}

closest("li") is necessary because the click target is whatever specific node the user clicked — it might be a <span>, an icon, or text inside the <li>, not the <li> itself. Walking up to the nearest matching ancestor is exactly how event delegation works in JavaScript ((e.target as HTMLElement).closest("li")). The Closure is forget()-ten because this listener should live as long as the page; there is no struct to own it and no intent to remove it, so leaking it for the program’s lifetime is the correct, idiomatic choice (the alternative — letting it drop — would make the listener dangle and throw on the first click). The handler needs the HtmlElement feature for class_list().toggle; this compiles cleanly against wasm32-unknown-unknown.

Manipulating the DOM from Rust with web-sys

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Getting the document: no ambient globals

Why DOM calls return Result and Option

The DOM class hierarchy and downcasting

Creating, configuring, and inserting nodes

Event listeners: closures that must outlive the call

Mutable shared state without &mut

Key Differences

Common Pitfalls

Pitfall 1: Forgetting the Cargo feature flag

Pitfall 2: Calling a subtype method on a generic Element

Pitfall 3: The dropped-closure runtime crash

Pitfall 4: Treating query_selector’s Option as the error

Pitfall 5: Reaching for &mut self in a handler

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Toggle a CSS class

Exercise 2: Build a list in one append

Exercise 3: Event delegation with one listener

Why DOM calls return `Result` and `Option`

Mutable shared state without `&mut`

Pitfall 2: Calling a subtype method on a generic `Element`

Pitfall 4: Treating `query_selector`’s `Option` as the error

Pitfall 5: Reaching for `&mut self` in a handler