Skip to content
Get packs

Guide · Open source

How to use Yoga: build, test and embed the flexbox layout engine

Updated · written with AI from the project's own documentation and checked against our catalogue data

Yoga is an embeddable flexbox layout engine. It works out where each element should go on screen and how large it should be, so other software can position items without writing its own layout logic. This guide explains what Yoga is for, how to build its C++ core and run the unit tests, how the test generator works, and where to find language bindings.

Yogareact/yoga · ★ 18.9k · MIT

Quick start

  1. 1Check prerequisites. Install a C++ 20 compiler and CMake. Add yarn classic only if you plan to generate tests.
  2. 2Build and test the core. From the Yoga directory, run ./unit_tests Debug or ./unit_tests Release. Ninja is used automatically if installed.
  3. 3Write an HTML fixture. Describe the node tree with inline styles and save it in gentest/fixtures.
  4. 4Install generator dependencies. Run yarn install to install the packages the test generator needs.
  5. 5Generate tests. Run yarn gentest in the yoga directory to turn fixtures into tests.
  6. 6Debug failing tests. Use the VSCode launch.json configuration to set breakpoints and debug with lldb or vsdbg.

What Yoga does and who it is for

Yoga calculates the position and size of each element in a layout tree. Your application hands it the structure and style rules, and Yoga returns the results, so your code does not need its own layout logic.

The README describes Yoga as having bindings for multiple languages. Packages are listed as available through npm, Maven Central and Swift Package Manager. It suits developers embedding flexbox-style layout into a native or cross-platform app, and teams that want the same layout rules across several languages. It is a code library with no visual interface, and the README does not describe it as a standalone website tool.

  • Good fit: embedding flexbox layout in a native or cross-platform app
  • Good fit: sharing one set of layout rules across languages
  • Good fit: contributing to the C++ layout core and its unit tests
  • Not a fit: building a web page directly
  • Not a fit: non-programmers looking for a visual tool

What you need before building Yoga

Building Yoga's main implementation requires a C++ 20 compiler and CMake. The build logic lives in CMake, and a wrapper script builds the main library and runs the unit tests.

Yarn classic is only needed if you want to generate tests from fixtures. Ninja is optional; the wrapper script will use it if it is installed, for faster builds.

  • C++ 20 compiler
  • CMake
  • yarn classic (only for generating tests)
  • ninja (optional, for faster builds)

Build Yoga and run the unit tests

Run the wrapper script from the Yoga directory with either a Debug or Release argument. Use Debug when you want to step through code and Release for an optimised build.

Yoga is also part of the vcpkg collection of ports maintained by Microsoft and community contributors. If the vcpkg version is out of date, the README asks you to open an issue or pull request on the vcpkg repository.

./unit_tests Debug ./unit_tests Release

Add new tests with HTML fixtures

Many of Yoga's tests are generated automatically from HTML fixtures that describe a node structure. The fixtures are rendered in Chrome to produce the expected layout result for each tree. You add new fixtures to the gentest/fixtures directory.

A fixture is ordinary HTML with inline styles. The example below is a container 100px square, centred items on the cross axis, containing a 50px square.

  • Install yarn classic.
  • Run yarn install to install dependencies for the test generator.
  • Run yarn gentest in the yoga directory to generate tests from your fixtures.
<div id="my_test" style="width: 100px; height: 100px; align-items: center;"> <div style="width: 50px; height: 50px;"></div> </div>

Debug unit tests in an editor

Yoga includes a VSCode launch.json configuration for debugging unit tests. Set your breakpoints, then run the configuration named Debug C++ Unit tests (lldb), or Debug C++ Unit tests (vsdbg) on Windows.

What people use it for

  • Positioning items in a native or cross-platform app without hand-written layout code
  • Keeping one set of flexbox-style layout rules across several language bindings
  • Adding regression tests for a layout case by writing an HTML fixture
  • Working on the C++ layout core and its unit tests

Frequently asked questions

Is Yoga free to use?

Yoga is released under the MIT licence, as listed on its project page. The MIT licence generally allows use, modification and redistribution, but read the licence file in the repository for the exact terms.

What do I need to build Yoga?

You need a C++ 20 compiler and CMake. Yarn classic is only required if you want to generate tests from HTML fixtures, and ninja is optional for faster builds.

How do I run Yoga's unit tests?

From the Yoga directory, run ./unit_tests Debug for a debug build or ./unit_tests Release for a release build. The script is a wrapper that builds the main library and runs the tests.

Can I install Yoga with npm or Maven?

The README says Yoga is available through npm, Maven Central and Swift Package Manager, and shows badges for each. The commands it gives for installing the library itself are not listed in this source, so check the package pages or the project homepage for setup details.

Is Yoga a good alternative to Taffy, Stretch or css-layout?

Taffy, Stretch and css-layout are comparable projects for layout. This guide does not benchmark them, so compare them on the features and language support you need. Yoga's README describes it as an embeddable, performant flexbox engine with bindings for multiple languages.

Can Yoga build a website for me?

No. The README does not describe Yoga as a standalone website tool. It is a layout library you embed in your own application, so you still need code to render the results.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Yoga suits developers who want flexbox-style layout inside a native or cross-platform app, especially if they need the same rules across several languages. It is also a good choice for contributors working on the C++ core. If you want to build a web page or need a visual tool, pick something else.

Install options & downloads