Pixi React

https://react.pixijs.io/
Admin
Pixi React is a library for writing PixiJS applications using React's declarative style and...
Tokens:3,143
Snippets:43
Trust Score:8.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Basic Application Setup

Source: https://react.pixijs.io/components/application

Use the Application component to wrap your PixiJS app. It accepts props compatible with PIXI.Application, such as autoStart and sharedTicker.

```javascript
import { Application } from '@pixi/react';

const MyComponent = () => (
    <Application autoStart sharedTicker />
);
```

--------------------------------

### Install @pixi/react dependencies

Source: https://react.pixijs.io/getting-started

Run this command to add the required Pixi.js and @pixi/react packages to your project.

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

--------------------------------

### Correct useApplication Usage

Source: https://react.pixijs.io/hooks/useApplication

This example shows the correct way to use the useApplication hook. The ChildComponent successfully accesses the parent application instance because it is rendered within the Application component.

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

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

    return <container />;
};

const MyComponent = () => (
    <Application>
        <ChildComponent />
    </Application>
);

```

--------------------------------

### Basic Pixi.js Components in React

Source: https://react.pixijs.io/components/pixi-components

List of commonly used Pixi.js components available with the `pixi` prefix after installing `@pixi/react`. These components map directly to Pixi.js classes.

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

```

--------------------------------

### Incorrect useApplication Usage

Source: https://react.pixijs.io/hooks/useApplication

This example demonstrates an incorrect usage of useApplication, which will cause an invariant violation because it's not properly nested within an Application component.

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

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

    return <Application />;
};

```

--------------------------------

### Using useExtend Hook in a React Component

Source: https://react.pixijs.io/hooks/useExtend

This example demonstrates how to use the `useExtend` hook to extend the `Container` class from PixiJS within a React component. Ensure `Application` is rendered to provide the necessary context.

```javascript
import {
    Application,
    useExtend,
} from '@pixi/react';
import { Container } from 'pixi.js';

function ChildComponent() {
    useExtend({ Container });

    return <pixiContainer />;
};

const MyComponent = () => (
    <Application>
        <ChildComponent />
    </Application>
);
```

--------------------------------

### Application with Resize Target

Source: https://react.pixijs.io/components/application

The Application component can be configured to resize based on a parent element. Pass a React ref directly to the resizeTo prop to achieve this.

```javascript
import { Application } from '@pixi/react';
import { useRef } from 'react';

const MyComponent = () => {
    const parentRef = useRef(null);

    return (
        <div ref={parentRef}>
            <Application resizeTo={parentRef} />
        </div>
    );
};
```

--------------------------------

### useTick with Options

Source: https://react.pixijs.io/hooks/useTick

Configure the useTick callback with options such as context, isEnabled, and priority. The callback function receives the context as 'this'.

```javascript
import {
    Application,
    useTick,
} from '@pixi/react';
import { UPDATE_PRIORITY } from 'pixi.js'
import { useRef } from 'react'

const ChildComponent = () => {
    const spriteRef = useRef(null)

    useTick({
        callback() {
            // this === context
            this.current.rotation += 1
        },
        context: spriteRef,
        isEnabled: true,
        priority: UPDATE_PRIORITY.HIGH,
    })

    return <pixiSprite ref={spriteRef} />
};

const MyComponent = () => (
    <Application>
        <ChildComponent />
    </Application>
);
```

--------------------------------

### Drawing with pixiGraphics Component

Source: https://react.pixijs.io/components/pixi-components

Shows how to use the `draw` prop on the `pixiGraphics` component. The `draw` prop accepts a callback function that receives the Pixi.js `Graphics` context and executes on every tick for dynamic drawing.

```jsx
<pixiGraphics draw={(graphics) => {  
    graphics.clear();  
    graphics.setFillStyle({ color: 'red' });  
    graphics.rect(0, 0, 100, 100);  
    graphics.fill();  
}} />  

```

--------------------------------

### Nesting Pixi.js Components with Properties

Source: https://react.pixijs.io/components/pixi-components

Demonstrates nesting Pixi.js components and applying properties. Properties of Pixi.js classes can be directly used as props on their corresponding React components.

```jsx
<pixiContainer x={100} y={100}>  
    <pixiSprite anchor={{ 0.5, 0.5 }} texture={texture} />  
</pixiContainer>  

```

--------------------------------

### Basic useTick Usage

Source: https://react.pixijs.io/hooks/useTick

Attach a simple callback to the Ticker to execute code on every frame. Ensure the parent component is wrapped in an Application.

```javascript
import {
    Application,
    useTick,
} from '@pixi/react';

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

const MyComponent = () => (
    <Application>
        <ChildComponent />
    </Application>
);
```

--------------------------------

### useTick with State Mutation (Potential Issue)

Source: https://react.pixijs.io/hooks/useTick

Demonstrates a common pitfall where mutating state directly within a non-memoized useTick callback can lead to performance issues due to re-renders. Avoid this pattern.

```javascript
import {
    Application,
    useTick,
} from '@pixi/react';
import { useState } from 'react'

const ChildComponent = () => {
    const [rotation, setRotation] = useState(0)

    useTick(() => setRotation(previousState => previousState + 1));

    return <pixiSprite rotation={rotation} />;
};

const MyComponent = () => (
    <Application>
        <ChildComponent />
    </Application>
);
```

--------------------------------

### Extend Pixi.js Container Component

Source: https://react.pixijs.io/extend

Use the `extend` API to make the Pixi.js `Container` available as a JSX component. This requires importing `extend` from `@pixi/react` and the `Container` from `pixi.js`.

```javascript
import {
    Application,
    extend,
} from '@pixi/react';
import { Container } from 'pixi.js';

extend({ Container });

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

```

--------------------------------

### useTick with Memoized Callback

Source: https://react.pixijs.io/hooks/useTick

Solves the performance issue by using useCallback to memoize the animation callback, preventing unnecessary re-renders and ensuring stable attachment to the Ticker.

```javascript
import {
    Application,
    useTick,
} from '@pixi/react';
import { useCallback, useState } from 'react'

const ChildComponent = () => {
    const [rotation, setRotation] = useState(0)

    const animateRotation = useCallback(() => setRotation(previousState => previousState + 1), []);

    useTick(animateRotation);

    return <pixiSprite rotation={rotation} />;
};

const MyComponent = () => (
    <Application>
        <ChildComponent />
    </Application>
);
```

--------------------------------

### Extend PixiJS React with Custom Viewport Component

Source: https://react.pixijs.io/components/custom-components

Use the `extend` API to register custom PixiJS components, such as a Viewport component from `pixi-viewport`, within your React application. Ensure TypeScript users consult specific documentation for prop support.

```javascript
import {
    Application,
    extend,
} from '@pixi/react';
import { Viewport } from 'pixi-viewport';

extend({ Viewport });

const MyComponent = () => (
    <Application>
        <pixiViewport>
            <pixiContainer />
        </pixiViewport>
    </Application>
);
```

--------------------------------

### Enable Unprefixed PixiJS Elements

Source: https://react.pixijs.io/typescript

Extend the `PixiElements` interface with `UnprefixedPixiElements` to use unprefixed component names (e.g., `<container>` instead of `<pixiContainer>`). Note that prefixed elements remain available to prevent collisions with other libraries.

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

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

--------------------------------

### Add Custom PixiJS Component to Type Catalogue

Source: https://react.pixijs.io/typescript

Declare custom components within the `PixiElements` interface in your global type definitions (`global.d.ts`). This enables type checking for your custom components, such as the `viewport` component from `pixi-viewport`.

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

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

--------------------------------

### Extend Built-in PixiJS Component Props

Source: https://react.pixijs.io/typescript

Use `PixiElements` to extend the props of built-in PixiJS components. This allows you to add custom properties or override existing ones for components like `pixiTilingSprite`.

```typescript
import { type Texture } from 'pixi.js';
import { type PixiElements } from '@pixi/react';

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