react-pixi-fiber: writing PixiJS scenes with React components

A renderer, not a wrapper, and that changes the ergonomics

The positioning is precise and it is worth being precise about it, because the name invites the wrong comparison. ReactPixiFiber is a React Fiber renderer for PixiJS, so it is not a set of helper components that wrap a Pixi display object each, it is a reconciler that treats the Pixi scene graph as the host tree. The practical consequence is that props, state, refs and effects all behave as they do elsewhere in React, and the component tree mirrors the display list rather than sitting beside it. The dependency list makes the mechanism explicit, with react-reconciler at 0.29.0 and fbjs as the only other runtime dependency, while PixiJS itself, prop-types, react and react-dom are all peer dependencies rather than bundled copies, which is the correct arrangement for a renderer because the host application owns those versions. The peer ranges tell you the support window. React and react-dom are 18.2.0 or newer, PixiJS is 4.4.0 up to but not including 8.0.0, and prop-types is 15.0.0 or newer.

Three ways in, and the one without ReactDOM is the unusual one

The usage section offers three setups and the third is the one that distinguishes this library. The first is the modern ReactDOM path, where a root is created from the client module and a Stage element wraps the scene, with the Stage carrying an options object holding the background colour and the dimensions:

import { createRoot } from "react-dom/client";
import { Sprite, Stage } from "react-pixi-fiber";
import bunny from "./bunny.png";

function Bunny (props) {
  return <Sprite texture={PIXI.Texture.from(bunny)} {...props} />;
}

const container = document.getElementById("container");
const root = createRoot(container);

root.render(
  <Stage options={{ backgroundColor: 0x10bb99, height: 600, width: 800 }}>
    <Bunny x={200} y={200} />
  </Stage>,
);

The second setup is for React 16 and 17, using the older render call with a container argument, and the documentation is careful that React 16 and 17 are supported by the 1.x line only while 2.x requires React 18.2 or newer. The third setup drops ReactDOM entirely. You construct a PixiJS application yourself with a canvas element as the view, and then render into the application's stage:

import { render, Text } from "react-pixi-fiber";
import * as PIXI from "pixi.js";

// Setup PixiJS Application
const canvasElement = document.getElementById("container")
const app = new PIXI.Application({
  backgroundColor: 0x10bb99,
  view: canvasElement,
  width: 800,
  height: 600,
});

render(
  <Text text="Hello World!" x={200} y={200} />, 
  app.stage
);

That last mode is the interesting one, because it means the renderer can be pointed at a Pixi application the host already owns, which is how you would embed a Pixi scene inside a page that ReactDOM does not control.

JSX is optional, and the alternative is a plain function call

One point in the documentation is easy to miss and it changes who the library is for. The HTML-like syntax called JSX is not required to use with this renderer, but it makes code more readable, and you can use Babel with a React preset to convert JSX into native JavaScript. The renderer is therefore not a JSX tool, it is a renderer, and the JSX layer is a convenience on top. That is a meaningful distinction for a library that is otherwise tied to React in the user's mental model, because it means you can drive a Pixi scene from a plain function that returns a description of the tree, without a build step for the JSX. The cost is that without JSX the syntax is noticeably clumsier, since each element becomes a function call with its props as an object. The documentation repeats the point in each of the three usage examples, which suggests the author knows it is the question people ask.

The version split, and what the 3.x line changes

The note at the top of the readme is the most important operational information in the project. The next major version is developed on a separate branch, and it splits the library into a core package and one adapter per React major and per PixiJS major, including the latest releases of both, published on npm under the alpha tag. The current branch is the 2.x line and takes bug fixes only. The release list reflects that, with the 3.0.0 alpha, a react-19 adapter alpha and a react-18 adapter alpha all published on the same day in October 2026. The rationale is straightforward once you see it. A renderer has to compile against a specific reconciler version and a specific host library version, and React and PixiJS both move fast, so supporting the latest of each in one package means a release cadence that breaks people. Splitting into a core and per-version adapters turns a hard dependency problem into a per-application choice, and the 2.x line stays where it is so existing applications are not forced to move. The cost is that the current line does not support PixiJS 8, and the peer range stops below 8.0.0.

What changed at 1.0 and what a migration involves

There is a dedicated migration guide for the 0.x line, and the first item on it is the one that will bite you. The built-in Stage and the one returned by the stage class factory were changed to have the same API, and the reason it matters is that it is now possible to get a ref to the built-in Stage. The advice is that unless you are using the class-based Stage component explicitly in your application, for example because you are extending it, you should prefer the built-in Stage rather than creating it with the factory. The data available on the Stage instance is documented, and the list includes the Pixi application instance and the canvas element, which is what a consumer needs in order to reach the renderer internals. The example directory in the repository has its own readme, a link script and its own package configuration, and the top level of the repository holds the built entry points for the CommonJS, ES module and UMD consumers, a type declaration file, an alias helper, the source directory, the test directory and the configuration files for Babel, ESLint and Prettier.

Running the examples and the state of the release

The examples are a separate package inside the repository, and the instructions to run them are four steps. You run the package install in the repository root, then the install again in the examples directory, then the start script in that directory, and then wait a few seconds for the examples to open in a new browser window. The same examples are published as CodeSandbox templates for JavaScript and TypeScript, both of them hello world, and there are more sandboxes for a rotating bunny, an animated sprite built with a custom component, aligning text, sharing Redux state and using an animated helper. The rotating bunny is the canonical demo and it is the one to look at first, because it is the smallest thing that shows a texture being placed and animated. The package metadata in the repository says version 2.0.0-rc.4, and the files list shows what actually ships, with the licence, the readme, the type declarations, the three built bundles, the alias helper and the source directory. The build is Rollup with the Babel, commonjs, node resolve and replace plugins, and the tests run under Jest with a WebGL canvas mock, which is how you test a renderer that draws to a canvas without a canvas.

Editorial conclusion

react-pixi-fiber is a good fit for a team whose PixiJS work already lives in a React codebase, because the display list becomes a component tree and the props become the scene graph, so state and effects work the way a React developer expects. It is the wrong tool if you need the newest PixiJS release, because the current line caps the peer dependency below version 8 and the 3.x work that supports the latest React and PixiJS is published under an alpha tag, so you would be adopting a prerelease. It is also the wrong tool if you want to keep React 16 or 17, since the 2.x line requires React 18.2 or newer and React 16 and 17 are only supported by the 1.x line. Before adopting it, check the compatibility matrix in the 3.x readme, and read the migration note, because the built-in Stage and the one returned by the stage class factory were unified in version 1.0. The project is MIT licensed, the last push was on 2026-10-14, and the current 2.x version in the package metadata is 2.0.0-rc.4.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. michalochman/react-pixi-fiber on GitHub
4. README
5. Releases