tawasuyu/taffy

1<!-- markdownlint-disable-next-line MD041 -->
2<p>
3<picture>
4  <img src="assets/logo.svg" alt="Taffy" height="70">
5</picture>
6</p>
7
8[![GitHub CI](https://github.com/DioxusLabs/taffy/actions/workflows/ci.yml/badge.svg)](https://github.com/DioxusLabs/taffy/actions/workflows/ci.yml)
9[![crates.io](https://img.shields.io/crates/v/taffy.svg)](https://crates.io/crates/taffy)
10[![docs.rs](https://img.shields.io/docsrs/taffy)](https://docs.rs/taffy)
11![Crates.io MSRV](https://img.shields.io/crates/msrv/taffy)
12
13Taffy is a flexible, high-performance, cross-platform UI layout library written in [Rust](https://www.rust-lang.org).
14
15It currently implements the CSS **Block**, **Flexbox** and **CSS Grid** layout algorithms. Support for other paradigms is planned. For more information on this and other future development plans see the [roadmap issue](https://github.com/DioxusLabs/taffy/issues/345).
16
17This crate is a collaborative, cross-team project, and is designed to be used as a dependency for other UI and GUI libraries.
18Right now, it powers:
19
20- [Servo](https://github.com/servo/servo): an alternative web browser
21- [Blitz](https://github.com/DioxusLabs/blitz): a radically modular web engine
22- [Bevy](https://bevyengine.org/): an ergonomic, ECS-first Rust game engine
23- [Takumi](https://github.com/kane50613/takumi): Renders your React components to images
24- [iocraft](https://github.com/ccbrown/iocraft): crafting beautiful interfaces for the terminal
25- [Slint](https://github.com/slint-ui/slint): a declarative GUI toolkit for building native user interfaces
26- The [Lapce](https://lapce.dev/) text editor via the [Floem](https://github.com/lapce/floem) UI framework
27- The [Zed](https://zed.dev/) text editor via the [GPUI](https://github.com/zed-industries/zed/tree/main/crates/gpui) UI framework
28
29## Usage
30
31```rust
32use taffy::prelude::*;
33
34// First create an instance of TaffyTree
35let mut tree : TaffyTree<()> = TaffyTree::new();
36
37// Create a tree of nodes using `TaffyTree.new_leaf` and `TaffyTree.new_with_children`.
38// These functions both return a node id which can be used to refer to that node
39// The Style struct is used to specify styling information
40let header_node = tree
41    .new_leaf(
42        Style {
43            size: Size { width: length(800.0), height: length(100.0) },
44            ..Default::default()
45        },
46    ).unwrap();
47
48let body_node = tree
49    .new_leaf(
50        Style {
51            size: Size { width: length(800.0), height: auto() },
52            flex_grow: 1.0,
53            ..Default::default()
54        },
55    ).unwrap();
56
57let root_node = tree
58    .new_with_children(
59        Style {
60            flex_direction: FlexDirection::Column,
61            size: Size { width: length(800.0), height: length(600.0) },
62            ..Default::default()
63        },
64        &[header_node, body_node],
65    )
66    .unwrap();
67
68// Call compute_layout on the root of your tree to run the layout algorithm
69tree.compute_layout(root_node, Size::MAX_CONTENT).unwrap();
70
71// Inspect the computed layout using `TaffyTree.layout`
72assert_eq!(tree.layout(root_node).unwrap().size.width, 800.0);
73assert_eq!(tree.layout(root_node).unwrap().size.height, 600.0);
74assert_eq!(tree.layout(header_node).unwrap().size.width, 800.0);
75assert_eq!(tree.layout(header_node).unwrap().size.height, 100.0);
76assert_eq!(tree.layout(body_node).unwrap().size.width, 800.0);
77assert_eq!(tree.layout(body_node).unwrap().size.height, 500.0); // This value was not set explicitly, but was computed by Taffy
78
79```
80
81## Bindings to other languages
82
83- Python via [stretchable](https://github.com/mortencombat/stretchable)
84- [WIP C bindings](https://github.com/DioxusLabs/taffy/pull/404)
85- [WIP WASM bindings](https://github.com/DioxusLabs/taffy/pull/394)
86
87## Learning Resources
88
89Taffy implements the Flexbox and CSS Grid specifications faithfully, so documentation designed for the web should translate cleanly to Taffy's implementation. For reference documentation on individual style properties we recommend the MDN documentation (for example [this page](https://developer.mozilla.org/en-US/docs/Web/CSS/width) on the `width` property). Such pages can usually be found by searching for "MDN property-name" using a search engine.
90
91If you are interested in guide-level documentation on CSS layout, then we recommend the following resources:
92
93### Flexbox
94
95- [Flexbox Froggy](https://flexboxfroggy.com/). This is an interactive tutorial/game that allows you to learn the essential parts of Flexbox in a fun engaging way.
96- [A Complete Guide To Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/) by CSS Tricks. This is detailed guide with illustrations and comprehensive written explanation of the different Flexbox properties and how they work.
97
98### CSS Grid
99
100- [CSS Grid Garden](https://cssgridgarden.com/). This is an interactive tutorial/game that allows you to learn the essential parts of CSS Grid in a fun engaging way.
101- [A Complete Guide To CSS Grid](https://css-tricks.com/snippets/css/complete-guide-grid/) by CSS Tricks. This is detailed guide with illustrations and comprehensive written explanation of the different CSS Grid properties and how they work.
102
103## Benchmarks (vs. [Yoga](https://github.com/facebook/yoga))
104
105- Run on a 2021 MacBook Pro with M1 Pro processor using [criterion](https://github.com/bheisler/criterion.rs)
106- The benchmarks measure layout computation only. They do not measure tree creation.
107- Yoga benchmarks were run via the [yoga](https://github.com/bschwind/yoga-rs) crate (Rust bindings)
108- Most popular websites seem to have between 3,000 and 10,000 nodes (although they also require text layout, which neither yoga nor taffy implement).
109
110Note that the table below contains multiple different units (milliseconds vs. microseconds)
111
112| Benchmark          | Node Count | Depth | Yoga ([ba27f9d]) | Taffy ([71027a8]) |
113| ---                | ---        | ---   | ---              | ---               |
114| yoga 'huge nested' | 1,000      | 3     | 364.60 µs        | 329.04 µs         |
115| yoga 'huge nested' | 10,000     | 4     | 4.1988 ms        | 4.3486 ms         |
116| yoga 'huge nested' | 100,000    | 5     | 45.804 ms        | 38.559 ms         |
117| big trees (wide)   | 1,000      | 1     | 737.77 µs        | 505.99 µs         |
118| big trees (wide)   | 10,000     | 1     | 7.1007 ms        | 8.3395 ms         |
119| big trees (wide)   | 100,000    | 1     | 135.78 ms        | 247.42 ms         |
120| big trees (deep)   | 4,000      | 12    | 2.2333 ms        | 1.7400 ms         |
121| big trees (deep)   | 10,000     | 14    | 5.9477 ms        | 4.4445 ms         |
122| big trees (deep)   | 100,000    | 17    | 76.755 ms        | 63.778 ms         |
123| super deep         | 1,000      | 1,000 | 555.32 µs        | 472.85 µs         |
124
125[ba27f9d]: https://github.com/facebook/yoga/commit/ba27f9d1ecfa7518019845b84b035d3d4a2a6658
126[71027a8]: https://github.com/DioxusLabs/taffy/commit/71027a8de03b343e120852b84bb7dca9fb4651c5
127
128## Contributions
129
130[Contributions welcome](https://github.com/DioxusLabs/taffy/blob/main/CONTRIBUTING.md):
131if you'd like to use, improve or build `taffy`, feel free to join the conversation, open an [issue](https://github.com/DioxusLabs/taffy/issues) or submit a [PR](https://github.com/DioxusLabs/taffy/pulls).
132If you have questions about how to use `taffy`, open a [discussion](https://github.com/DioxusLabs/taffy/discussions) so we can answer your questions in a way that others can find.