0
# @pixi/react
1

2
@pixi/react is a React integration library for PixiJS that enables declarative 2D graphics programming using JSX. It bridges React's component-based architecture with PixiJS's high-performance 2D graphics rendering, providing hooks, components, and a type-safe API for building interactive graphics applications.
3

4
## Package Information
5

6
- **Package Name**: @pixi/react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install pixi.js@^8.2.6 @pixi/react`
10

11
## Core Imports
12

13
```typescript
14
import { Application, createRoot, extend } from "@pixi/react";
15
import { useApplication, useTick, useExtend } from "@pixi/react";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { Application, createRoot, extend, useApplication, useTick, useExtend } = require("@pixi/react");
22
```
23

24
Type imports:
25

26
```typescript
27
import type { ApplicationRef, PixiElements, PixiReactElementProps, UnprefixedPixiElements } from "@pixi/react";
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { Application, extend } from "@pixi/react";
34
import { Container, Graphics } from "pixi.js";
35
import { useCallback } from "react";
36

37
// Register PixiJS components for JSX usage
38
extend({ Container, Graphics });
39

40
const MyComponent = () => {
41
  const drawCallback = useCallback((graphics) => {
42
    graphics.clear();
43
    graphics.setFillStyle({ color: "red" });
44
    graphics.rect(0, 0, 100, 100);
45
    graphics.fill();
46
  }, []);
47

48
  return (
49
    <Application>
50
      <pixiContainer x={100} y={100}>
51
        <pixiGraphics draw={drawCallback} />
52
      </pixiContainer>
53
    </Application>
54
  );
55
};
56
```
57

58
## Architecture
59

60
@pixi/react is built around several key components:
61

62
- **Component Extension System**: The `extend()` function registers PixiJS classes for JSX usage, enabling selective imports
63
- **React Integration**: Full React lifecycle support with context, refs, and hooks
64
- **Reconciler**: Custom React reconciler manages PixiJS display objects as React components
65
- **Type System**: Complete TypeScript integration with type-safe JSX elements for all PixiJS components
66
- **Hook System**: React hooks for accessing application state, ticker integration, and dynamic component registration
67

68
## Capabilities
69

70
### Application Component
71

72
Root component that creates and manages a PixiJS Application with React lifecycle integration. Handles canvas creation, application initialization, and context provision.
73

74
```typescript { .api }
75
interface ApplicationProps extends BaseApplicationProps, Partial<ApplicationOptions> {
76
  className?: string;
77
  children?: PixiReactChildNode;
78
  defaultTextStyle?: TextStyle | TextStyleOptions;
79
  extensions?: (ExtensionFormatLoose | any)[];
80
  onInit?: (app: Application) => void;
81
  resizeTo?: HTMLElement | Window | RefObject<HTMLElement | null>;
82
}
83

84
const Application: React.ForwardRefExoticComponent<ApplicationProps & React.RefAttributes<ApplicationRef>>;
85
```
86

87
[Application Component](./application.md)
88

89
### Root Creation
90

91
Imperative API for creating PixiJS React roots, useful for custom integration scenarios and programmatic application management.
92

93
```typescript { .api }
94
function createRoot(
95
  target: HTMLElement | HTMLCanvasElement,
96
  options?: CreateRootOptions
97
): Root;
98

99
interface CreateRootOptions {
100
  onInit?: (app: PixiApplication) => void;
101
}
102

103
interface Root {
104
  render(children: ReactNode, applicationOptions: ApplicationOptions): Promise<PixiApplication>;
105
}
106
```
107

108
[Root Creation](./root-creation.md)
109

110
### Component Extension
111

112
System for registering PixiJS components for JSX usage, enabling selective imports and bundle size optimization.
113

114
```typescript { .api }
115
function extend(objects: { [key: string]: new (...args: any) => any }): void;
116
```
117

118
[Component Extension](./component-extension.md)
119

120
### React Hooks
121

122
Collection of hooks for accessing PixiJS application state, integrating with the ticker system, and dynamically extending components.
123

124
```typescript { .api }
125
function useApplication(): ApplicationState;
126
function useTick<T>(options: TickerCallback<T> | UseTickOptions<T>): void;
127
function useExtend(objects: Parameters<typeof extend>[0]): void;
128
```
129

130
[React Hooks](./hooks.md)
131

132
### JSX Elements
133

134
Type-safe JSX elements for all PixiJS components, supporting both prefixed (`pixiContainer`) and unprefixed (`container`) usage patterns.
135

136
```typescript { .api }
137
interface PixiElements extends PrefixedPixiElements {}
138

139
type PixiReactElementProps<T extends new (...args: any) => any> =
140
  BaseNodeProps<InstanceType<T>>
141
  & GraphicsProps<InstanceType<T>>
142
  & EventHandlers
143
  & ConstructorOptions<T>;
144
```
145

146
[JSX Elements](./jsx-elements.md)
147

148
## Types
149

150
```typescript { .api }
151
interface ApplicationRef {
152
  getApplication(): PixiApplication | null;
153
  getCanvas(): HTMLCanvasElement | null;
154
}
155

156
interface ApplicationState {
157
  app: PixiApplication;
158
  isInitialised: boolean;
159
  isInitialising: boolean;
160
}
161

162
interface UseTickOptions<T> {
163
  callback: TickerCallback<T>;
164
  context?: T;
165
  isEnabled?: boolean;
166
  priority?: number;
167
}
168

169
type PixiReactChildNode = BasePixiReactNode | Iterable<BasePixiReactNode> | ReactNode;
170
```