Yoga API

Most applications should use OpenTUI layout options. Read Layout for the normal Flexbox API.

@opentui/core/yoga is an advanced facade over the native Yoga library. Use it when you need to own a Yoga tree and calculate its layout directly. The entry point works in Bun and supported Node.js releases.

Imports#

The @opentui/core root exports the module as the Yoga namespace. The direct entry point exports the same named values and types.

import { Yoga } from "@opentui/core"

const node = Yoga.Node.create()
node.free()

The direct entry point also has a default export named Yoga:

import Yoga, { Config, Direction, Node, type Layout } from "@opentui/core/yoga"

The default object contains Config, Node, every enum except YogaStatus, and every uppercase constant on this page. YogaError, YogaStatus, and type-only exports such as Layout are not properties of the default object.

Minimal layout#

import { Direction, Node } from "@opentui/core/yoga"

const node = Node.create()

try {
  node.setWidth(80)
  node.setHeight(24)
  node.calculateLayout(undefined, undefined, Direction.LTR)
  console.log(node.getComputedLayout())
} finally {
  node.free()
}

calculateLayout() accepts a number, "auto", or undefined for each available size. Both "auto" and undefined pass an undefined constraint to Yoga. The direction defaults to Direction.LTR.

Ownership#

Config.create() and each Node factory allocate native objects. The JavaScript garbage collector does not release these objects.

• Call config.free() or Config.destroy(config) for each owned config.
• Call node.free() or Node.destroy(node) for one node.
• Call node.freeRecursive() to release a node and its current descendants.
• Release a node tree before you release the config that created it. config.free() throws while nodes from that config remain.
• removeChild() and removeAllChildren() detach nodes. They do not free them.
• free(), freeRecursive(), and both static destroy() methods ignore repeated release calls.
• node.isFreed() reports whether the wrapper released its native node.

node.reset() resets the native node and removes its measure and dirtied callbacks. It throws YogaError while the node has a parent or children. Node release also removes callback registrations. Most methods of a released wrapper do nothing or return a default value. Do not keep using a released wrapper.

Native Yoga calls throw YogaError for invalid arguments, such as an out-of-range child index or an unknown enum value. Its operation property names the call, and its status property holds a YogaStatus value.

Config.ptr and Node.ptr expose binding pointers. They are implementation-looking public properties. Do not use them as a standalone native API.

Config#

Node#

Factories and tree ownership#

Layout state#

Enum styles#

Each setter has the getter shown in the same row.

Numeric and value styles#

A numeric value uses Yoga points. A percentage string such as "50%" uses Unit.Percent. undefined clears an optional style value.

The Accepted values column describes setter arguments. Getters do not return undefined. Numeric getters return numbers. After you clear a numeric style, getFlexGrow() and getFlexShrink() return Yoga’s default of 0. The other numeric getters return NaN. After you clear a value style, its getter returns a Value with Unit.Undefined and value: NaN. On a new node, getWidth(), getHeight(), and getFlexBasis() return Unit.Auto. The other value getters return Unit.Undefined.

Baselines and containing blocks#

Measure and dirtied callbacks#

MeasureFunction has this shape:

type MeasureFunction = (width: number, widthMode: MeasureMode, height: number, heightMode: MeasureMode) => Size

Use setMeasureFunc(callback) to register it. Use unsetMeasureFunc() or pass null to remove it. hasMeasureFunc() reports whether the node has a measure function.

An undefined size constraint reaches the callback as NaN with MeasureMode.Undefined. The callback returns { width, height }.

A node has one measure function, and a new one replaces the old one. Standalone nodes measure only through JavaScript measure functions.

setDirtiedFunc(callback) registers a DirtiedFunction. Yoga calls it with the matching Node when clean state changes to dirty state. Use unsetDirtiedFunc() or pass null to remove it.

Yoga calls both callbacks synchronously on the JavaScript thread. A callback must not return a Promise. A Promise result throws TypeError. A callback must not change any Yoga node. A change throws. If a callback throws, the Yoga call that ran it, such as calculateLayout(), throws the same error after Yoga returns.

Each Config creates one native measure trampoline and one dirtied trampoline when the first of its nodes registers a callback. config.free() closes them. A trampoline routes each call through the node pointer. Release and reset operations remove the per-node registrations.

Types#

Enums and constants#

Each uppercase name is an alias for the matching enum member.

ExperimentalFeature.WebFlexBasis and EXPERIMENTAL_FEATURE_WEB_FLEX_BASIS are experimental. The rest of this entry point is advanced, not experimental.

Related reference#

• API and symbol index
• Package entry points
• Layout