ReactPixiFiber is a JavaScript library for writing PixiJS applications using React declarative style in React 16 and above.
For React <16.0.0 see react-pixi.
See Rotating Bunny demo.
Also, please explore our CodeSandbox templates:
and examples:
0.x.y
? πRead migration guide.
The current version assumes React >16.0.0 and PixiJS >4.4.0
yarn add react-pixi-fiber prop-types pixi.js
or
npm install react-pixi-fiber prop-types pixi.js --save
Refer to next sections to see usage examples.
This package works flawlessly with Create React App β see examples below, they already use it.
yarn install
(or npm install
) in the repository root.yarn install
(or npm install
) in the examples
directory.yarn start
(or npm run start
) in the examples
directory.react-pixi-fiber@0.x.y
(before version 1.0.0
)Stage
and the one returned by createStageClass()
to have the same API
PIXI.Application
exposed by Stage
to be React ref
oldProps
in customApplyProps
to not be initialised when the component is first rendered
applyProps
to applyDisplayObjectProps
react-pixi
It is possible to use React Pixi Fiber as a drop-in replacement for react-pixi
.
There are two options:
import
or require
statementswebpack
resolve alias
React Pixi Fiber currently supports following components out of the box (but read Custom Components section if you need more):
<Stage />
Renders Root Container of any PIXI.Application
.
Expects one the following props:
app
- pass your own PIXI.Application
instance,options
- pass only the PIXI.Application
options.<Container />
Renders PIXI.Container
.
<Graphics />
Renders PIXI.Graphics
.
<ParticleContainer />
Renders PIXI.ParticleContainer
(or PIXI.particles.ParticleContainer
if you're using PixiJS 4).
<Sprite />
Renders PIXI.Sprite
.
<TilingSprite />
Renders PIXI.TilingSprite
(or PIXI.extras.TilingSprite
if you're using PixiJS 4).
<Text />
Renders PIXI.Text
.
<BitmapText />
Renders PIXI.BitmapText
(or PIXI.extras.BitmapText
if you're using PixiJS 4).
<NineSlicePlane />
Renders PIXI.NineSlicePlane
.
Similarly to ReactDOM in React 16,
ReactPixiFiber is not ignoring unknown PIXI.DisplayObject
members β they are all passed through. You can read
more about Unknown Prop Warning in ReactDOM.
In case you are using PixiJS plugins, such as pixi-layers
, ReactPixiFiber can
recognize these custom props by using the following CustomPIXIProperty
API:
CustomPIXIProperty(maybeComponentType, propertyName, validator)
accepts:
maybeComponentType
β a ReactPixiFiber component, an array of ReactPixiFiber components or undefined
/null
. Passing undefined
or null
will apply custom property to all ReactPixiFiber components.propertyName
β a name of the custom property as string. ReactPixiFiber will also check that the casing is correct.validator
β optional function that will be called with value provided and should return true
if the value is valid, false
otherwise.For example:
import { Container, Sprite } from "react-pixi-fiber";
const group = new PIXI.display.Group(0, true);
// if you just want to get rid of Unknown Prop Warning:
CustomPIXIProperty(Container, "parentGroup");
CustomPIXIProperty(undefined, "zIndex");
// if you want to be strict in the values that are provided
CustomPIXIProperty(Container, "parentGroup", value => value instanceof PIXI.display.Group);
CustomPIXIProperty([Container, Sprite], "zIndex", value => Number.isFinite(value));
function App() {
return (
<Container>
<Container parentGroup={group}>
<Sprite texture={PIXI.Texture.WHITE} x={10} y={10} zIndex={1} />
<Sprite texture={PIXI.Texture.WHITE} x={15} y={15} zIndex={2} />
</Container>
{/* `parentgroup` below will trigger prop warning, as the letter casing is incorrect */}
<Container parentgroup={group}>
<Sprite texture={PIXI.Texture.WHITE} x={100} y={100} zIndex={1} />
{/* `zindex` below will trigger prop warning, as the letter casing is incorrect */}
<Sprite texture={PIXI.Texture.WHITE} x={105} y={105} zindex={2} />
</Container>
</Container>
)
}
For setting properties on PixiJS types that are either PIXI.Point
s or PIXI.ObservablePoint
s you can use either
and array of integers or a comma-separated string of integers in the following forms: [x,y]
, "x,y"
, [i]
, "i"
.
In the case where two integers are provided, the first will be applied to the x
coordinate and the second will be
applied to the y
coordinate. In the case where a single integer if provided, it will be applied to both coordinates.
You can still create your own PIXI Point
or ObservablePoint
objects and assign them directly to the property.
These won't actually replace the property but they will be applied using the original object's .copy()
method.
PIXI.Application
instance created by <Stage />
PIXI.Application
is automatically provided using the following definition (either as a prop or in context):
app
β an instance of PixiJS Application, with properties like:
loader
β Loader instance to help with asset loading,renderer
β WebGL or CanvasRenderer,ticker
β Ticker for doing render updates,view
β reference to the renderer's canvas element. withApp
Higher-Order Component (with all React versions)
ReactPixiFiber can recognize your custom components using API compatible with react-pixi
.
CustomPIXIComponent(behavior, type)
accepts a behavior
object with the following 4 properties and a type
string.
customDisplayObject(props)
Use this to create an instance of [PIXI.DisplayObject].
This is your entry point to custom components and the only required method. Can be also passed as behavior
of type function
to CustomPIXIComponent
.
customApplyProps(displayObject, oldProps, newProps)
(optional)Use this to apply newProps
to your Component
in a custom way.
Note: this replaces the default method of transfering props
to the specified displayObject
. Call this.applyDisplayObjectProps(oldProps,newProps)
inside your customApplyProps
method if you want that.
customDidAttach(displayObject)
(optional)Use this to do something after displayObject
is attached, which happens after componentDidMount
lifecycle method.
customWillDetach(displayObject)
(optional)Use this to do something (usually cleanup) before detaching, which happens before componentWillUnmount
lifecycle method.
For example, this is how you could implement Rectangle
component:
// components/Rectangle.js
import { CustomPIXIComponent } from "react-pixi-fiber";
import * as PIXI from "pixi.js";
const TYPE = "Rectangle";
export const behavior = {
customDisplayObject: props => new PIXI.Graphics(),
customApplyProps: function(instance, oldProps, newProps) {
const { fill, x, y, width, height } = newProps;
instance.clear();
instance.beginFill(fill);
instance.drawRect(x, y, width, height);
instance.endFill();
}
};
export default CustomPIXIComponent(behavior, TYPE);
// App.js
import { render } from "react-pixi-fiber";
import * as PIXI from "pixi.js";
import Rectangle from "./components/Rectangle"
// Setup PixiJS Application
const canvasElement = document.getElementById("container")
const app = new PIXI.Application(800, 600, {
view: canvasElement
});
render(
<Rectangle
x={250}
y={200}
width={300}
height={200}
fill={0xFFFF00}
/>,
app.stage
);
Yes and it's awesome! It is battle tested and backed up by Kalamba Games since the conception in the beginning of 2018 (after migrating from react-pixi
) and now also used by other game studios.
PixiJS v4, v5 and v6 are supported.
Sure thing! We've got you covered.
PIXI.Application
?Yes, you can pass app
property to Stage
component, e.g. <Stage app={app} />
.
react-pixi
?Yes, it is easy, read migration guide.
No, unfortunately it is not supported right now.
The main purpose of this repository is to be able to render PixiJS objects inside React 16 Fiber architecture.
Development of React Pixi Fiber happens in the open on GitHub, and I would be grateful to the community for any contributions, including bug reports and suggestions.
Read below to learn how you can take part in improving React Pixi Fiber.
React Pixi Fiber has adopted a Contributor Covenant Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.
Read the contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to React Pixi Fiber.
You can help others and discuss in our gitter channel.
ReactPixiFiber is MIT licensed.
react-pixi
For making PIXI available in React for the first time.
For deeply explaining the concepts of Fiber architecture.
For helping me understand how to build an actual renderer.
On which this renderer was initially based.
For making an awesome project structure and documentation that is used in similar fashon here.