Repository files navigation

Simply the best way to write PixiJS applications in React
_{WritePixiJS applications using React declarative style 👌}

@pixi/react is an open-source, production-ready library to render high performant PixiJS applications in React.

• React v19 support
• PixiJS v8 support

If you want to start a new React project from scratch then we recommendCreate React App, but@pixi/react should work with any React application (Remix, Next.js, etc).To add@pixi/react to an existing React application, just install the dependencies:

npm install pixi.js@^8.2.6 @pixi/react

import{Application,extend,}from'@pixi/react'import{Container,Graphics,}from'pixi.js'import{useCallback}from'react'extend({  Container,  Graphics,})constMyComponent=()=>{constdrawCallback=useCallback(graphics=>{graphics.clear()graphics.setFillStyle({color:'red'})graphics.rect(0,0,100,100)graphics.fill()},[])return(<Application><pixiContainerx={100}y={100}><pixiGraphicsdraw={drawCallback}/></pixiContainer></Application>)}

One of the most important concepts to understand with v8 isextend. Normally@pixi/react would have to import all pf Pixi.js to be able to provide the full library as JSX components. Instead, we use an internal catalogue of components populated by theextend API. This allows you to define exactly which parts of Pixi.js you want to import, keeping your bundle sizes small.

To allow@pixi/react to use a Pixi.js component, pass it to theextend API:

import{Container}from'pixi.js'import{extend}from'@pixi/react'extend({ Container})constMyComponent=()=>(<pixiContainer/>)

The<Application> component is used to wrap your@pixi/react app. The<Application> component can takeall props that can be set onPIXI.Application.

import{Application}from'@pixi/react'constMyComponent=()=>{return(<ApplicationautoStartsharedTicker/>)}

defaultTextStyle is a convenience property. Whatever is passed will automatically be assigned to Pixi.js'sTextStyle.defaultTextStyle.

extensions is an array of extensions to be loaded. Adding and removing items from this array will automatically load/unload the extensions. The first time this is handled happens before the application is initialised. See Pixi.js'sextensions documentation for more info on extensions.

The<Application> component supports theresizeTo property, with some additional functionality: it can accept any HTML elementor it can take a Reactref directly.

import{Application}from'@pixi/react'import{useRef}from'react'constMyComponent=()=>{constparentRef=useRef(null)return(<divref={parentRef}><ApplicationresizeTo={parentRef}/></div>)}

All other components should be included in your IDE's intellisense/autocomplete once you've installed/imported@pixi/react. If it's exported from Pixi.js, it's supported as a component with thepixi prefix. Here's a selection of commonly used components:

<pixiContainer/><pixiGraphics/><pixiSprite/><pixiAnimatedSprite/><pixiText/><pixiHtmlText/>

ThepixiGraphics component has a specialdraw property.draw takes a callback which receives theGraphics context, allowing drawing to happen on every tick.

constMyComponent=()=>{return(<pixiGraphicsdraw={graphics=>{graphics.clear()graphics.setFillStyle({color:'red'})graphics.rect(0,0,100,100)graphics.fill()}}/>)}

@pixi/react supports custom components via theextend API. For example, you can create a<viewport> component using thepixi-viewport library:

import{extend}from'@pixi/react'import{Viewport}from'pixi-viewport'extend({ Viewport})constMyComponent=()=>{<viewport><pixiContainer/></viewport>}

Theextend API will teach@pixi/react about your components, but TypeScript won't know about them nor their props. If you're using Typescript, check out ourdocs for Typescript Users.

useApplication allows access to the parentPIXI.Application created by the<Application> component. This hookwill not work outside of an<Application> component. Additionally, the parent application is passed viaReact Context. This meansuseApplication will only work appropriately inchild components, and in the same component that creates the<Application>.

For example, the following exampleuseApplicationwill not be able to access the parent application:

import{Application,useApplication,}from'@pixi/react'constParentComponent=()=>{// This will cause an invariant violation.const{ app}=useApplication()return(<Application/>)}

Here's a working example whereuseApplicationwill be able to access the parent application:

import{Application,useApplication,}from'@pixi/react'constChildComponent=()=>{const{ app}=useApplication()console.log(app)return(<container/>)}constParentComponent=()=>(<Application><ChildComponent/></Application>)

useExtend allows theextend API to be used as a React hook. Additionally, theuseExtend hook is memoised, while theextend function is not.

import{Container}from'pixi.js'import{useExtend}from'@pixi/react'constMyComponent=()=>{useExtend({ Container})return(<container/>)}

useTick allows a callback to be attached to theTicker on the parent application.

import{useTick}from'@pixi/react'constMyComponent=()=>{useTick(()=>console.log('This will be logged on every tick'))}

useTick optionally takes an options object. This allows control of allticker.add options, as well as adding theisEnabled option. SettingisEnabled tofalse will cause the callback to be disabled until the argument is changed to true again.

import{useState}from'react'import{useTick}from'@pixi/react'constMyComponent=()=>{const[isEnabled,setIsEnabled]=useState(false)useTick(()=>console.log('This will be logged on every tick as long as `isEnabled` is `true`'),isEnabled)return(<spriteonClick={setIsEnabled(previousState=>!previousState)}>  )}

import{useState}from'react'import{useTick}from'@pixi/react'constMyComponent=()=>{const[count,setCount]=useState(0)useTick(()=>setCount(previousCount=>previousCount+1))returnnull}

import{useCallback,useState,}from'react'import{useTick}from'@pixi/react'constMyComponent=()=>{const[count,setCount]=useState(0)constupdateCount=useCallback(()=>setCount(previousCount=>previousCount+1),[])useTick(updateCount)}

@pixi/react already offers types for built-in components, but custom components need to be added to the library's type catalogue so it knows how to handle them. This can be achieved by adding your custom components to thePixiElements interface. Here's what it may look like to add theviewport component from our earlierextend example:

// global.d.tsimport{typePixiReactElementProps}from'@pixi/react'import{typeViewport}from'pixi-viewport'declare module'@pixi/react'{interfacePixiElements{viewport:PixiReactElementProps<typeofViewport>;}}

Now you'll be able to use your custom component in your project without any type errors!

If you like to live life on the wild side, you can enable unprefixed Pixi elements (i.e.<container> instead of<pixiContainer>) by adding theUnprefixedPixiElements interface to thePixiElements interface.

// global.d.tsimport{typeUnprefixedPixiElements}from'@pixi/react'declare module'@pixi/react'{interfacePixiElementsextendsUnprefixedPixiElements{}}

The prefixed and unprefixed elements have the same functionality, but we recommend sticking to the prefixed components to avoid collisions with other libraries that add intrinsic elements to JSX (such asreact-dom and@react-three/fiber).

The props for built-in components are available on thePixiElements type and can be used to extend the built-in types.

import{typePixiElements}from'@pixi/react'exporttypeTilingSpriteProps=PixiElements['pixiTilingSprite']&{image?:string;texture?:Texture;};