A lightweight but featureful virtual DOM library, primarily for web use.
no_std and no dependencies without the "callbacks" feature.
Please use cargo-edit to always add the latest version of this library:
cargo add lignin && cargo add -D lignin --features callbacksSome type constraints are more strict with the "callbacks" feature enabled, so make sure to always check this way!
When writing a renderer that supports callbacks, instead use
cargo add lignin --features callbacksto always enable the feature.
Enables DOM callback support. Off by default. Requires std.
Apps or components can be written against the callback API without enabling this feature, in which case those code paths can be erased at compile-time.
use lignin::{Node, Element, ElementCreationOptions};
// Please bring your own allocator where necessary.
let _ = &Node::HtmlElement {
element: &Element {
name: "DIV", // Use all-caps for more efficient DOM interactions.¹
creation_options: ElementCreationOptions::new(), // `const fn` builder and getter/setter patterns for extensible interfaces.
attributes: &[],
content: Node::Multi(&[
"Hello! ".into(), // Some convenience included.
Node::Comment {
comment: "--> Be mindful of HTML pitfalls. <!--", // Renderers must validate.
dom_binding: None,
}
]),
event_bindings: &[], // Strongly typed using `web-sys`.
},
dom_binding: None, // For JS interop.
}
.prefer_thread_safe(); // Thread-safety can be inferred from bindings!¹ See Element.tagName (MDN). This avoids case-insensitive comparisons.
There are a few ecosystem compatibility rules that aren't covered by Rust's type system or the unsafe keyword. Please see the main module documentation for more information.
- Dodrio, which didn't quite satisfy my requirements but generally inspired this approach.
To Dronaroid for finding a great name for this library, @platy for criticism and pushing me towards a better implementation, and everyone on the Rust Programming Language Community Server discord who answered my questions that came up during the rewrite.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
See CONTRIBUTING for more information.
lignin strictly follows Semantic Versioning 2.0.0 with the following exceptions:
- The minor version will not reset to 0 on major version changes (except for v1).
Consider it the global feature level. - The patch version will not reset to 0 on major or minor version changes (except for v0.1 and v1).
Consider it the global patch level.
This includes the Rust version requirement specified above.
Earlier Rust versions may be compatible, but this can change with minor or patch releases.
Which versions are affected by features and patches can be determined from the respective headings in CHANGELOG.md.
Note that dependencies of this crate may have a more lenient MSRV policy!
Please use cargo +nightly update -Z minimal-versions in your automation if you don't generate Cargo.lock manually (or as necessary) and require support for a compiler older than current stable.