Blitz Documentation

Blitz provides two main high-level wrappers depending on your use case:

• blitz: An HTML/markdown frontend for rendering HTML strings. It is useful for previewing files but currently lacks interactivity. It uses blitz-dom, blitz-html, blitz-shell, and blitz-renderer-vello.
• dioxus-native: A Dioxus frontend that renders a Dioxus VirtualDom. It supports full interactivity via Dioxus event handling. It uses blitz-dom, dioxus-core, blitz-shell, and blitz-renderer-vello.

Both wrappers can optionally use blitz-net to fetch sub-resources.

The accesskit_xplat crate provides a cross-platform AccessKit adapter that does not depend on winit. This allows you to use AccessKit with any version of Winit (including beta or git versions) without version mismatch issues.

Note: This crate requires slightly more boilerplate code than accesskit_winit and is used at the developer's own risk as per AccessKit developer notes regarding implementation optimality.

To keep the accessibility tree in sync with your application window, you must manually call adapter methods when window events occur:

• Focus: Call adapter.set_focus(bool) when the window focus changes.
• Bounds: Call adapter.set_window_bounds(outer_rect, inner_rect) when the window is moved or resized. Rect objects are provided by the accesskit crate.

match event {
    WindowEvent::Focused(is_focused) => {
        self.adapter.set_focus(*is_focused);
    }
    WindowEvent::Moved(_) | WindowEvent::SurfaceResized(_) => {
        // ... calculate positions and sizes ...
        self.adapter.set_window_bounds(
            Rect::from_origin_size(outer_position, outer_size),
            Rect::from_origin_size(inner_position, inner_size),
        )
    }
    _ => (),
}

You can explore Blitz by running the included packages and examples from the repository.

To run the browser package:

cargo run --release --package browser

To run specific examples:

• TODO app: cargo run --release --package todomvc
• Markdown renderer: cargo run --release --package readme ./README.md
• WGPU texture integration: cargo run --release --package wgpu_texture

To build Blitz examples for the browser, you must install the wasm32-unknown-unknown target and the trunk build tool.

rustup target add wasm32-unknown-unknown
cargo install trunk

You can build and serve WASM examples using either the just command from the repository root or by using trunk directly from the specific example directory. The builds use relative paths (--public-url ./) to ensure the dist/ folder can be served from any URL or opened via file://.

# Using just from the repo root
just wasm-build EXAMPLE     # build to examples/EXAMPLE/dist
just wasm-serve EXAMPLE     # build + serve with live reload

# Using trunk directly from the example directory
trunk build --release
trunk serve --release

On Linux/Unix, accesskit_xplat internally spawns asynchronous tasks. While the API is blocking, you must configure the crate based on your async runtime:

• Tokio: Enable the tokio feature in your Cargo.toml.
• Other Runtimes/No Runtime: Use the default features.

If you need the latest features or bug fixes from the development version of dioxus-native, you can use the git version from the Blitz repository.

Follow these steps:

1. Remove your dependency on the dioxus crate entirely.
2. Add dioxus-native pointing to the Blitz repository with a specific revision.
3. Update your imports: change use dioxus::prelude::*; to use dioxus_native::prelude::*;.
4. If you need specific functionality from the dioxus crate not in the prelude, import it from individual sub-crates like dioxus-html, dioxus-signals, or dioxus-router.

Note: The git version still depends on the stable v0.7.x version of Dioxus from crates.io, so compatible libraries like dioxus-sdk or dioxus-components should still work.

dioxus-native = { git = "https://github.com/DioxusLabs/blitz", rev = "e64a3d8", features = ["prelude"] }

Blitz WASM examples use data-wasm-opt="z" in index.html to trigger Binaryen's -Oz size optimization pass. To further reduce over-the-wire size for production deployments, you should pre-compress the .wasm and .js files using Brotli, as trunk does not compress output by default.

brotli -q 11 -f dist/*.wasm dist/*.js

The blitz-dom crate provides a headless DOM implementation via BaseDocument. It is designed to be driven by external code. Most users should use higher-level wrappers instead of using blitz-dom directly:

• HtmlDocument (from blitz-html): For parsing HTML/XHTML and integrating with markdown converters like comrak or pulldown-cmark.
• DioxusDocument (from dioxus-native): For combining a BaseDocument with a Dioxus VirtualDom to enable dynamic rendering and event handling.

blitz-dom handles the DOM tree, CSS parsing/resolution, layout, and event handling, allowing any renderer to interact with the DOM.

Dioxus Native supports several feature flags to enable specific capabilities:

• default: Enables the standard features.
• accessibility: Enables accesskit accessibility support.
• hot-reload: Enables hot-reloading of Dioxus RSX.
• menu: Enables the muda menubar.
• tracing: Enables tracing support.
• net: Enables networking support (requires tokio runtime on non-WASM targets).
• html: Enables the HTML parser provider.
• vello or vello-hybrid: Enables Vello-based rendering, allowing configuration of Features and Limits.