Crate vertigo

Source

Expand description

§Vertigo

A reactive Real-DOM library with SSR for Rust.

MIT or Apache 2.0 licensed

§Features

Reactive dependencies - A graph of values and clients (micro-subscriptions) that can automatically compute what to refresh after one value changes
Real DOM - No intermediate Virtual DOM mechanism is necessary
HTML/CSS macros - Allows to construct Real DOM nodes using HTML and CSS
Tailwind v4 support out of the box
Isomorphic server-side rendering - The same WASM code is used for both client and server (see: vertigo-cli)
Fullstack - Can be mounted into actix-web (see: vertigo-cli)

See Changelog for recent features.

Go to TUTORIAL if you want to try.

Having trouble with cargo install vertigo-cli? Check BUILDING.md.

For more information go to vertigo home website vertigo.znoj.pl.

§Examples

Dependencies:

vertigo = "0.14"

Example 1:

use vertigo::{dom, DomNode, Value, bind, main};

#[main]
pub fn app() -> DomNode {
    let count = Value::new(0);

    let increment = bind!(count, |_| {
        count.change(|value| {
            *value += 1;
        });
    });

    let decrement = bind!(count, |_| {
        count.change(|value| {
            *value -= 1;
        });
    });

    dom! {
        <html>
            <head/>
            <body>
                <div>
                    <p>"Counter: " { count }</p>
                    <button on_click={decrement}>"-"</button>
                    <button on_click={increment}>"+"</button>
                </div>
            </body>
        </html>
    }
}

Example 2:

use vertigo::{css, component, DomNode, store, Value, dom, main};

#[component]
pub fn MyMessage(message: Value<String>) {
    dom! {
        <p>
            "Message to the world: "
            { message }
        </p>
    }
}

#[store]
fn state_message() -> Value<String> {
    Value::new("Hello world!".to_string())
}

#[main]
fn app() -> DomNode {
    let main_div = css! {"
        color: darkblue;
    "};

    dom! {
        <html>
            <head/>
            <body>
                <div css={main_div}>
                    <MyMessage message={state_message()} />
                </div>
            </body>
        </html>
    }
}

Take a look at More examples here.

§Installation of `vertigo-cli` tool

To ease process or development use vertigo-cli tool that allows to build, serve and watch your project.

cargo install --force vertigo-cli

§Demo App

§Prepare

Install just (1.46 or newer) and vertigo-cli:

cargo install just vertigo-cli

§Run

Build and run project using:

just demo

Eventually terminal will let you know that app is available under http://localhost:4444/

If you want to play around with the demo code, run:

just demo-watch

It should automatically recompile upon changes and the browser tab should be informed to refresh. Note that this compiles the code in debug mode so the WASM is not optimized.

To run the examples in watch mode (they will run on localhost:4444): just examples-counter or just examples-router or just examples-trafficlights

§A community, soon to grow

Discord server: https://discord.gg/HAXtTeFrAf

§Short-links to most commonly used things

DOM creation
- main - Wraps function to be vertigo entry-point
- dom! - Builds DomNode using RSX/rstml (HTML-like) syntax
- css! - Builds Css using CSS-like syntax
- tw! - Wraps tailwind class names
- component - Wraps function to be used as component in RSX
Data storing
- Value - Read-write reactive value
- Computed - Read-only (computed) reactive value
- keyed_computed_list - Stable per-key Computeds from a reactive list
- LazyCache - Lazy cache for fetched resources
- LazyListCache - Lazy cache for fetched lists (optimized for CRUD operations)
- WsCollection - Reactive collection driven by a server subscription over a WebSocket
- store - Wraps function to be used as a store (singleton) generator
Others
- bind! - Auto-clones variables before use
- get_driver - Access to browser facilities
- router::Router - Hash or history routing

§Guides

guides::reactive_graph - how Value, Computed and subscribe are wired together
guides::collection_key_and_list_renderers - CollectionKey and the memoized list renderers
guides::lazy_list_cache - LazyListCache: optimistic, per-item reactive list cache
guides::websocket_collection - WsCollection: server-pushed reactive collections over a WebSocket

Re-exports§

pub use driver_module::driver::Driver;
pub use driver_module::driver::FetchMethod;
pub use driver_module::driver::FetchResult;
pub use driver_module::driver::get_driver;
pub use driver_module::driver::transaction;
pub use driver_module::js_value::JsJson;
pub use driver_module::js_value::JsJsonContext;
pub use driver_module::js_value::JsJsonDeserialize;
pub use driver_module::js_value::JsJsonNumber;
pub use driver_module::js_value::JsJsonSerialize;
pub use driver_module::js_value::JsObject;
pub use driver_module::js_value::from_json;
pub use driver_module::js_value::to_json;
pub use reactive::ByRc;
pub use reactive::Computed;
pub use reactive::Context;
pub use reactive::DropResource;
pub use reactive::GraphId;
pub use reactive::Reactive;
pub use reactive::ToComputed;
pub use reactive::Value;
pub use render::RenderValue;
pub use render::collection::CollectionKey;
pub use log;

Modules§

dev
external_api
guides: Long-form guides rendered as their own documentation pages.
html_entities: Constants of unicode signs labeled with HTML entities names
prelude
reactive: Transactional reactive graph with equality cutoff.
render
router
self

Macros§

bind: Allows to conveniently clone values into closure.
bind_rc: Allows to create an event handler based on provided arguments which is wrapped in Rc
bind_spawn: Allows to create an event handler based on provided arguments which launches an asynchronous action
computed_tuple: Allows to create Computed<(T1, T2, ...)> out of Value<T1>, Value<T2>, …
css: Allows to create Css styles for usage in dom! macro.
css_block: Constructs a CSS block that can be manually pushed into existing Css styles instance.
dom: Allows to create DomNode using RSX/rstml (HTML-like) syntax.
dom_debug: Version of dom! macro that additionally emits compiler warning with generated code.
dom_element: Allows to create DomElement using HTML tags.
include_static: Allows to include a static file
js: Macro that allows to evaluate pseudo-JavaScript expressions.
js_inner: Used internally by js! macro.
tw: Allows to trace tailwind class names.

Structs§

AutoMap: A structure similar to HashMap but allows to provide a function create for creating a new value if particular key doesn’t exists.
ClickEvent: Structure passed as a parameter to callback on on_click event.
Css: CSS styles definition for use in DOM.
DomComment: A Real DOM representative - comment kind
DomElement: A Real DOM representative - element kind
DomElementRef: A reference to DomElement.
DomId
DomText: A Real DOM representative - text kind
Drawing: A picture for a <canvas>: operations of its 2D context, in order, recorded in Rust and played back in the browser.
Driver: Set of functions to communicate with the browser.
DropFileEvent
DropFileItem
Instant: Monotonically non-decreasing clock using a driver, similar to std::time::Instant.
IntersectionEvent: Structure passed as a parameter to the callback on the on_intersect event.
JsJsonContext
JsJsonNumber
JsObject: The string-keyed map behind JsJson::Object.
KeyDownEvent: Structure passed as a parameter to callback on on_key_down event.
KeyedListItem: One entry in a keyed_computed_list: a stable key plus a per-item value.
LazyCache: A structure similar to Value but supports Loading/Error states and automatic refresh after defined amount of time.
LazyListCache: A lazy cache for lists that stores items in an ordered dict T::Key -> ListItem<T::Value>.
MarkerContent: A marker created with DomComment::new_marker renders its content as siblings placed just before the marker comment. Reporting those ids here lets the marker carry them along when it is moved inside its parent, instead of tearing the content down and building it again — so DOM state (focus, selection, scroll position, running animations) survives a move.
MediaEvent: Structure passed as a parameter to callback on on_media event: what happened to a <video> or an <audio>, and its state right after.
MessageEvent: Structure passed as a parameter to callback on on_message event: a message the page in a frame (<iframe>) sent to the page with the frame, with parent.postMessage.
PointerEvent: Structure passed as a parameter to callback on on_pointer_down, on_pointer_move, on_pointer_up and on_pointer_cancel events.
RequestBuilder: Builder for typed requests.
RequestResponse: Result from request made using RequestBuilder.
TwClass: This represents a tailwind class. Use tw! macro to create one.
ViewBox: The units of a Drawing: a rectangle fitted into the canvas as an SVG viewBox with preserveAspectRatio="xMidYMid meet" is, as big as fits and in the middle. What lies outside the box is drawn too, in the margins it leaves.
WebsocketClose: How a websocket closed, after a connection or after an attempt to connect that failed.
WebsocketConnection: Represents websocket connection.
WebsocketOptions: How a websocket connects and reconnects, for Driver::websocket_with_options.
WheelEvent: Structure passed as a parameter to callback on on_wheel event.
WsCollection: A single server-pushed subscription reconciled into a reactive list.
WsQuery: Builder for a server subscription query.
WsSocket: One WebSocket connection shared across every subscription.

Enums§

AttrGroupValue
AttrText: The text of an attribute, in whichever form costs nothing to keep hold of.
AttrValue
CollectionWhereValue
CssAttrValue
CssGroup: Css chunk, represented either as static or dynamic string.
DomNode: A Real DOM representative.
FetchMethod
JsJson: JSON object serialized to travel between JS-WASM boundary.
LineCap: How the ends of lines look, as lineCap of the 2D context.
LineJoin: How lines turn a corner, as lineJoin of the 2D context.
MediaEventKind: What happened to a <video> or an <audio>: the media events the driver listens to for on_media, under their DOM names.
PointerType: What a PointerEvent comes from.
RequestBody
Resource: The state of the resource.
WebsocketMessage: Websocket message type on which a websocket handler operates.
WheelDeltaMode: The unit of the deltas of a WheelEvent.
WsMessageKind
WsServerMessageFrom

Traits§

DomDisplay: Opt-in: lets a Display type of your own be rendered by vertigo - as an attribute value, and as a text node in dom!.
EmbedDom: Can be embedded into dom! macro
IntoAttrValue: The bound on every attribute value - what DomElement::attr and the dom! macro accept.
IntoCollectionWhereValue: Converts a value into CollectionWhereValue for WsQuery::eq / WsQuery::gt / WsQuery::lt.
JsJsonDeserialize
JsJsonSerialize

Functions§

from_json: Deserialize from JsJson to T
get_driver
keyed_computed_list: Maps a reactive list into a reactive list of per-item Computeds, reusing the same Computed instance for each key across updates (Solid <For>-style).
spawn: Spawn a future - thus allowing to fire async functions in, for example, event handler. Handy when fetching resources from internet.
start_app: Starting point of the app (used by vertigo::main macro, which is preferred)
to_json: Serialize T to JsJson
transaction: Do bunch of operations on dependency graph without triggering anything in between.

Type Aliases§

AttrGroup: Type interpreted as component’s dynamic attributes groups
AuthTokenProvider: Supplies the auth token sent with every Subscribe.
FetchResult: Result from request made using RequestBuilder.
InstantType: Duration in seconds, returned from Instant methods.
MergeFn: Reconciles an incoming Set model (new) against the previously stored one (prev), returning the model to store. The default merge simply returns new (full replacement); callers can opt into a custom merge via WsCollection::new_with_merge to carry forward fields that live updates omit (e.g. an image URL only present in the initial snapshot).

Attribute Macros§

component: Macro which transforms a provided function into a component that can be used in dom! macro
main: Marco that marks an entry point of the app
store: Wraps a function generating a resource out of parameters, and creates a store.

Derive Macros§

AutoJsJson: Macro for creating JsJson from structures and structures from JsJson.

Crate vertigo

Crate vertigo Copy item path

§Vertigo

§Features

§Examples

§Installation of vertigo-cli tool

§Demo App

§Prepare

§Run

§A community, soon to grow

§Short-links to most commonly used things

§Guides

Re-exports§

Modules§

Macros§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate vertigo

§Installation of `vertigo-cli` tool