web-sysCrate

Overview

web-sys is the browser, as Rust types. Window, Document, Element, fetch, localStorage, canvas, WebGL, WebRTC, the clipboard — all of it, generated mechanically from the WebIDL files that specify the web platform. That generation is the crate's defining fact, and it explains everything else about how it feels to use.

Start with the thing that catches everyone: every type is behind its own Cargo feature, and nothing is enabled by default. The crate declares over 1700 of them. A fresh dependency gives you an empty namespace, and the error reads as though the crate were broken:

// With `features = ["Window", "Document", "Element"]` in Cargo.toml:
use web_sys::{window, Document, Element};

// Without them, this same line is:
//   error[E0432]: unresolved import `web_sys::Document`
//   no `Document` in the root

The gating exists because enabling everything would mean compiling bindings for the entire web platform on every build. So the workflow is: write the code, read the compiler error, add the feature, repeat. Features are named exactly after the WebIDL interface — HtmlInputElement, CanvasRenderingContext2d, console — and docs.rs lists the required feature on every item's page.

Three consequences of being generated, all worth expecting before you meet them:

• Nullable becomes Option, throwing becomes Result. window() returns Option<Window> because there is no window in a worker. document() is Option too. So reaching the body is a chain of fallible steps, which is honest about a platform where any of them can be absent.
• Overloads become suffixed method names. JavaScript's one fetch taking different argument shapes becomes fetch_with_str, fetch_with_request_and_init and so on. The names are long and the right one is found by reading the list.
• Everything needs casting. get_element_by_id returns Option<Element>, because that is what the IDL says, and Element has no .value(). Reaching an input's text means a dyn_into::<HtmlInputElement>(). This is constant, and wasm_bindgen::JsCast must be in scope for it.

The crate is not ergonomic and does not try to be — it is a complete, correct, low-level surface that higher-level crates build on. If you want something that feels like Rust, a framework such as leptos, yew or dioxus sits on top of this. Use web-sys directly when you want a specific browser API, not an application framework.

It is part of the wasm-bindgen family and released in lockstep with it; js-sys covers the JavaScript language where this covers the browser. MSRV is 1.81.

When to use it

use wasm_bindgen::prelude::*;
use wasm_bindgen::JsCast;
use web_sys::{window, Document, HtmlInputElement};

#[wasm_bindgen]
pub fn greet_from_field() -> Result<String, JsValue> {
    // Each step is fallible, because in some contexts each is absent.
    let document: Document = window()
        .ok_or("no window")?
        .document()
        .ok_or("no document")?;

    // Element has no .value(); HtmlInputElement does.
    let name = document
        .get_element_by_id("name")
        .and_then(|element| element.dyn_into::<HtmlInputElement>().ok())
        .map(|input| input.value())
        .unwrap_or_else(|| "world".to_string());

    let greeting = document.create_element("p")?;
    greeting.set_text_content(Some(&format!("Hello, {name}!")));
    document.body().ok_or("no body")?.append_child(&greeting)?;

    Ok(name)
}

use wasm_bindgen::prelude::*;
use wasm_bindgen::JsCast;
use wasm_bindgen_futures::JsFuture;
use web_sys::{window, Request, RequestInit, Response};

pub async fn get_text(url: &str) -> Result<String, JsValue> {
    let options = RequestInit::new();
    options.set_method("GET");
    let request = Request::new_with_str_and_init(url, &options)?;

    let response_value = JsFuture::from(
        window().ok_or("no window")?.fetch_with_request(&request),
    )
    .await?;

    // fetch resolves to a JsValue, so the concrete type needs a cast.
    let response: Response = response_value.dyn_into()?;

    // A 404 is a successful fetch: ok() is the check that matters.
    if !response.ok() {
        return Err(JsValue::from(format!("status {}", response.status())));
    }

    let text = JsFuture::from(response.text()?).await?;
    Ok(text.as_string().unwrap_or_default())
}

use wasm_bindgen::prelude::*;
use wasm_bindgen::JsCast;
use web_sys::{console, window, MouseEvent};

#[wasm_bindgen]
pub fn wire_up() -> Result<(), JsValue> {
    let document = window().ok_or("no window")?.document().ok_or("no doc")?;
    let button = document.create_element("button")?;

    // The closure must outlive this function, since the DOM holds it.
    let on_click = Closure::<dyn FnMut(MouseEvent)>::new(|event: MouseEvent| {
        console::log_1(&JsValue::from(format!("clicked at {}", event.client_x())));
    });

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

    // Deliberately leaked: the listener lives as long as the page.
    on_click.forget();
    Ok(())
}

API map

The crate is far too large to map. What follows is the handful of entry points everything else is reached through, plus the conventions that let you find a method you have not seen before.

use wasm_bindgen::prelude::*;
use web_sys::{window, Document, Window};

#[wasm_bindgen]
pub fn page_info() -> Result<String, JsValue> {
    let win: Window = window().ok_or("no window")?;
    let doc: Document = win.document().ok_or("no document")?;

    let title = doc.title();
    let _url = doc.url()?;
    let _width = win.inner_width()?;

    Ok(title)
}

use wasm_bindgen::prelude::*;
use web_sys::console;

#[wasm_bindgen]
pub fn log_things() {
    console::log_1(&JsValue::from("a message"));
    console::warn_1(&JsValue::from("a warning"));
    console::error_1(&JsValue::from("a problem"));

    // The suffix is the argument count, matching console.log(a, b).
    console::log_2(&JsValue::from("value:"), &JsValue::from(42));
}

use wasm_bindgen::prelude::*;
use wasm_bindgen::JsCast;
use web_sys::{window, HtmlInputElement};

#[wasm_bindgen]
pub fn read_input(id: &str) -> Option<String> {
    let document = window()?.document()?;
    let element = document.get_element_by_id(id)?;

    // Checked: None if the element is not actually an input.
    let input: HtmlInputElement = element.dyn_into().ok()?;
    Some(input.value())
}

use wasm_bindgen::prelude::*;
use web_sys::{Request, RequestInit};

#[wasm_bindgen]
pub fn build_request(url: &str) -> Result<Request, JsValue> {
    // new_with_str: the overload taking just a URL string.
    let simple = Request::new_with_str(url)?;
    let _ = simple;

    // new_with_str_and_init: the one taking a URL and an options object.
    let options = RequestInit::new();
    options.set_method("POST");
    Request::new_with_str_and_init(url, &options)
}

use wasm_bindgen::prelude::*;
use web_sys::window;

#[wasm_bindgen]
pub fn remember(key: &str, value: &str) -> Result<Option<String>, JsValue> {
    // Two Results deep: local_storage() can throw, and may be None.
    let storage = window()
        .ok_or("no window")?
        .local_storage()?
        .ok_or("storage unavailable")?;

    storage.set_item(key, value)?;
    storage.get_item(key)
}

use wasm_bindgen::prelude::*;
use wasm_bindgen::JsCast;
use web_sys::{window, CanvasRenderingContext2d, HtmlCanvasElement};

#[wasm_bindgen]
pub fn draw(canvas_id: &str) -> Result<(), JsValue> {
    let document = window().ok_or("no window")?.document().ok_or("no doc")?;

    let canvas: HtmlCanvasElement = document
        .get_element_by_id(canvas_id)
        .ok_or("no canvas")?
        .dyn_into()?;

    // get_context returns Option<Object>: the context type may be unsupported.
    let context: CanvasRenderingContext2d = canvas
        .get_context("2d")?
        .ok_or("no 2d context")?
        .dyn_into()?;

    context.set_fill_style_str("#336699");
    context.fill_rect(10.0, 10.0, 100.0, 50.0);
    Ok(())
}