Configuration

Optimize Taffy for your specific use case.

Taffy works out-of-the-box, but you can tune it for performance, precision, or resource constraints.

Capacity Pre-allocation

If you know roughly how many nodes you'll need, initializing the tree with a capacity can reduce memory re-allocations and improve startup performance.

Rounding Settings

Control whether computed layout boxes are snapped to integer coordinates or retain fractional values. Sizes are calculated from rounded edges, so adjacent boxes can receive different rounded widths. Margins and detailed Grid track data can remain fractional even with rounding enabled.

Memory Management

TaffyTree, Style, Layout, and TaffyError objects own WASM allocations. When the environment supports FinalizationRegistry, the bindings register automatic cleanup, but its timing is not guaranteed. Use .free() for deterministic cleanup, and do not access an object after freeing it.

To prevent memory spikes or leaks in the WASM heap, you should explicitly manage memory:

• Reuse: Use .clear() to remove all nodes while retaining allocated node capacity. Existing node IDs become invalid.
• Dispose: Use .free() if you are completely done with a tree and want to release its memory immediately.

Node creation and setStyle() copy styles into the tree. getStyle(), getLayout(), and the fifth measure-callback argument return independent owned objects: free those copies when finished. Freeing the tree does not free copies you already obtained. Ordinary DTOs such as layout.size and detailedLayoutInfo() are JavaScript data and have no .free() method.

const tree = new TaffyTree();

const style = new Style({ width: 100, height: 50 });
const node = tree.newLeaf(style);
style.free(); // The tree has its own style copy.
tree.computeLayout(node, { width: 100, height: 50 });
const layout = tree.getLayout(node);
console.log(layout.size);
layout.free();

// Reuse the tree if more nodes will be needed.
// Clears all nodes but keeps memory allocated
tree.clear();

// Free the tree when completely finished.
tree.free();

Next Steps

• 🎨 Styling Guide - Learn about Flexbox and Grid.
• 🛠️ Advanced Topics - Debugging and Internals.