gem-hunter

Simply the best way to write PixiJS applications in React
_{Write PixiJS 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 recommend Create 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,
})

const MyComponent = () => {
  const drawCallback = useCallback(graphics => {
    graphics.clear()
    graphics.setFillStyle({ color: 'red' })
    graphics.rect(0, 0, 100, 100)
    graphics.fill()
  }, [])

  return (
    <Application>
      <pixiContainer x={100} y={100}>
        <pixiGraphics draw={drawCallback} />
      </pixiContainer>
    </Application>
  )
}

One of the most important concepts to understand with v8 is extend. 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 the extend 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 the extend API:

import { Container } from 'pixi.js'
import { extend } from '@pixi/react'

extend({ Container })

const MyComponent = () => (
  <pixiContainer />
)

The <Application> component is used to wrap your @pixi/react app. The <Application> component can take all props that can be set on PIXI.Application.

import { Application } from '@pixi/react'

const MyComponent = () => {
  return (
    <Application
      autoStart
      sharedTicker />
  )
}

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

When an <Application> is unmounted, it will call the destroy() method on the Pixi.js application instance. Provide this prop to override the default DestroyOptions (the second argument to destroy()). See Pixi.js's destroy documentation for more info.

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's extensions documentation for more info on extensions.

When an <Application> is unmounted, it will call the destroy() method on the Pixi.js application instance. Provide this prop to override the default RendererDestroyOptions (the first argument to destroy()). See Pixi.js's destroy documentation for more info.

The <Application> component supports the resizeTo property, with some additional functionality: it can accept any HTML element or it can take a React ref directly.

import { Application } from '@pixi/react'
import { useRef } from 'react'
const MyComponent = () => {
  const parentRef = useRef(null)
  return (
    <div ref={parentRef}>
      <Application resizeTo={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 the pixi prefix. Here's a selection of commonly used components:

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

The pixiGraphics component has a special draw property. draw takes a callback which receives the Graphics context, allowing drawing to happen on every tick.

const MyComponent = () => {
  return (
    <pixiGraphics draw={graphics => {
      graphics.clear()
      graphics.setFillStyle({ color: 'red' })
      graphics.rect(0, 0, 100, 100)
      graphics.fill()
    }} />
  )
}

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

import { extend } from '@pixi/react'
import { Viewport } from 'pixi-viewport'

extend({ Viewport })

const MyComponent = () => {
  <viewport>
    <pixiContainer />
  </viewport>
}

The extend 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 our docs for Typescript Users.

useApplication allows access to the parent PIXI.Application created by the <Application> component. This hook will not work outside of an <Application> component. Additionally, the parent application is passed via React Context. This means useApplication will only work appropriately in child components, and in the same component that creates the <Application>.

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

import {
  Application,
  useApplication,
} from '@pixi/react'

const ParentComponent = () => {
  // This will cause an invariant violation.
  const { app } = useApplication()

  return (
    <Application />
  )
}

Here's a working example where useApplication will be able to access the parent application:

import {
  Application,
  useApplication,
} from '@pixi/react'

const ChildComponent = () => {
  const { app } = useApplication()

  console.log(app)

  return (
    <container />
  )
}

const ParentComponent = () => (
  <Application>
    <ChildComponent />
  </Application>
)

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

import { Container } from 'pixi.js'
import { useExtend } from '@pixi/react'

const MyComponent = () => {
  useExtend({ Container })

  return (
    <container />
  )
}

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

import { useTick } from '@pixi/react'

const MyComponent = () => {
  useTick(() => console.log('This will be logged on every tick'))
}

useTick optionally takes an options object. This allows control of all ticker.add options, as well as adding the isEnabled option. Setting isEnabled to false will cause the callback to be disabled until the argument is changed to true again.

import { useState } from 'react'
import { useTick } from '@pixi/react'

const MyComponent = () => {
  const [isEnabled, setIsEnabled] = useState(false)

  useTick(() => console.log('This will be logged on every tick as long as `isEnabled` is `true`'), isEnabled)

  return (
    <sprite onClick={setIsEnabled(previousState => !previousState)}>
  )
}

import { useState } from 'react'
import { useTick } from '@pixi/react'

const MyComponent = () => {
  const [count, setCount] = useState(0)

  useTick(() => setCount(previousCount => previousCount + 1))

  return null
}

import {
  useCallback,
  useState,
} from 'react'
import { useTick } from '@pixi/react'

const MyComponent = () => {
  const [count, setCount] = useState(0)

  const updateCount = 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 the PixiElements interface. Here's what it may look like to add the viewport component from our earlier extend example:

// global.d.ts
import { type PixiReactElementProps } from '@pixi/react'
import { type Viewport } from 'pixi-viewport'

declare module '@pixi/react' {
  interface PixiElements {
    viewport: PixiReactElementProps<typeof Viewport>;
  }
}

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 the UnprefixedPixiElements interface to the PixiElements interface.

// global.d.ts
import { type UnprefixedPixiElements } from '@pixi/react'

declare module '@pixi/react' {
  interface PixiElements extends UnprefixedPixiElements {}
}

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 as react-dom and @react-three/fiber).

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

import { type PixiElements } from '@pixi/react'

export type TilingSpriteProps = PixiElements['pixiTilingSprite'] & {
  image?: string;
  texture?: Texture;
};