React template
The React template renders PixiJS from React components with @pixi/react. It's built on the Vite template, so the scripts, the public/ folder and the dev port all work the same way.
- npm
- yarn
- pnpm
- bun
npm create pixi.js@latest my-app -- --template framework-react
yarn create pixi.js my-app --template framework-react
pnpm create pixi.js my-app --template framework-react
bun create pixi.js my-app --template framework-react
Use framework-react-js for JavaScript.
Project structure
my-app/
├── public/
│ ├── assets/
│ │ └── bunny.png
│ ├── favicon.png
│ └── style.css
├── src/
│ ├── App.tsx
│ ├── main.tsx
│ ├── pixi-react.d.ts
│ └── vite-env.d.ts
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts
Config files for oxlint, oxfmt, VS Code and git sit at the root as in every template. vite.config.ts adds @vitejs/plugin-react, and src/main.tsx mounts <App /> into #pixi-container.
Register PixiJS classes with extend
@pixi/react only knows about the PixiJS classes you pass to extend. Each one becomes a JSX element with a pixi prefix:
import { extend } from "@pixi/react";
import { Sprite } from "pixi.js";
extend({ Sprite });
After this, <pixiSprite> is available. Add Container to the same call to use <pixiContainer>, and so on. Using an element you haven't registered throws an error. Registering only what you use keeps the bundle small.
To draw shapes, register Graphics and pass a draw callback:
import { extend } from "@pixi/react";
import { Graphics } from "pixi.js";
import { useCallback } from "react";
extend({ Graphics });
function Box() {
const draw = useCallback((graphics: Graphics) => {
graphics.clear();
graphics.rect(0, 0, 100, 100).fill(0xe91e63);
}, []);
return <pixiGraphics draw={draw} />;
}
Create the app with Application
<Application> creates the PixiJS Application and its canvas. It takes the same options as app.init():
import { Application } from "@pixi/react";
export default function App() {
return (
<Application background="#1099bb" resizeTo={window} antialias>
<SpinningCube />
<BunnySprite />
</Application>
);
}
antialias smooths the edges of 3D shapes. Children draw in order, so the bunny draws in front of the cube. Components inside <Application> can call useApplication() to reach the app. The template uses it to keep the bunny centered on the screen.
Run code every frame with useTick
useTick adds a callback to the app's ticker and removes it when the component unmounts:
import { useApplication, useTick } from "@pixi/react";
import { Assets, Sprite, Texture } from "pixi.js";
import { useEffect, useRef, useState } from "react";
const BunnySprite = () => {
const { app } = useApplication();
const spriteRef = useRef<Sprite>(null);
const [texture, setTexture] = useState(Texture.EMPTY);
useEffect(() => {
Assets.load<Texture>("assets/bunny.png").then(setTexture);
}, []);
useTick((ticker) => {
const sprite = spriteRef.current;
if (!sprite) return;
sprite.position.set(app.screen.width / 2, app.screen.height / 2);
sprite.rotation += 0.1 * ticker.deltaTime;
});
return <pixiSprite ref={spriteRef} texture={texture} anchor={0.5} />;
};
The bunny moves and rotates by changing the sprite through a ref, not through React state. Setting its position every frame keeps it centered after the window resizes. Per-frame changes stay out of React's render cycle, which keeps them fast. If the callback sets React state, wrap it in useCallback, because useTick re-adds the callback whenever it changes.
Draw 3D with View3D
The template also passes View3D from PixiJS 3D to extend, which adds <pixiView3D>. A View3D is a 2D display object that draws a 3D scene, so it goes in JSX like a sprite:
import {
CubeGeometry,
DirectionalLight,
Material3D,
Mesh3D,
View3D,
} from "@pixi/3d";
import { extend, useTick } from "@pixi/react";
import { useEffect, useRef } from "react";
extend({ View3D });
const environment = { skyColor: 0xc9d6ff, groundColor: 0x3a2f45 };
const SpinningCube = () => {
const viewRef = useRef<View3D>(null);
const cubeRef = useRef<Mesh3D>(null);
useEffect(() => {
const view = viewRef.current!;
const cube = new Mesh3D({
geometry: new CubeGeometry(),
material: new Material3D({ baseColor: 0xe72264 }),
});
const sun = new DirectionalLight({ intensity: 3 });
sun.position.set(-3, 5, 2);
sun.lookAt(cube.position);
view.root.addChild(cube, sun);
view.camera.position.set(0, 1.6, 3);
view.camera.lookAt(cube.position);
cubeRef.current = cube;
return () => {
cubeRef.current = null;
cube.destroy({ geometry: true, material: true });
sun.destroy();
};
}, []);
useTick((ticker) => {
const cube = cubeRef.current;
if (!cube) return;
cube.rotation.y += 0.01 * ticker.deltaTime;
});
return <pixiView3D ref={viewRef} autoResize environment={environment} />;
};
The 3D scene inside the view isn't JSX. Meshes and lights go under view.root, which @pixi/react doesn't manage, so the effect builds them and keeps the cube in a ref for useTick. Its cleanup destroys them when the component unmounts, and before a hot reload runs the effect again. destroy also takes each one out of the view, and the geometry and material flags destroy the cube's geometry and material too. autoResize makes the view fill the screen. PixiJS 3D explains the lights and the camera.
In TypeScript, src/pixi-react.d.ts adds pixiView3D to @pixi/react's element types. Classes from pixi.js are typed already, so add a line there only for other classes you pass to extend.
Linting
The React template's oxlint config adds the react plugin with three rules: rules-of-hooks as an error, and exhaustive-deps and only-export-components as warnings. See linting and formatting.
Learn more
The @pixi/react documentation covers custom components, TypeScript types for them, and the other hooks.