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, and every uppercase constant on this page. Type-only exports such as Layout are not properties of the runtime 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.
• 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() removes its measure and dirtied callbacks before it resets the native node. Node release also removes callback registrations. Methods guard a released wrapper, but application code should not keep using one.

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. Value getters return a Value with Unit.Undefined and value: NaN for an unset value.

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 Yoga node has one measure slot. A JavaScript measure function replaces native-backed measurement on that node. Native-backed measurement can also replace the JavaScript function.

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.

The facade shares one native trampoline for all measure callbacks and one for all dirtied callbacks. It 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