0
# Component Extension
1

2
The component extension system allows you to register PixiJS classes for use as JSX elements. This selective import approach keeps bundle sizes small and provides type-safe access to PixiJS components.
3

4
## Capabilities
5

6
### Extend Function
7

8
Registers PixiJS components for JSX usage, enabling selective imports and bundle optimization.
9

10
```typescript { .api }
11
/**
12
 * Expose Pixi.js components for use in JSX
13
 * @param objects - Object mapping component names to PixiJS constructor classes
14
 */
15
function extend(objects: { [key: string]: new (...args: any) => any }): void;
16
```
17

18
**Usage Examples:**
19

20
```typescript
21
import { extend } from "@pixi/react";
22
import { 
23
  Container, 
24
  Graphics, 
25
  Text, 
26
  Sprite, 
27
  TilingSprite,
28
  ParticleContainer 
29
} from "pixi.js";
30

31
// Basic component registration
32
extend({
33
  Container,
34
  Graphics,
35
  Text,
36
});
37

38
// Now you can use these as JSX elements
39
const BasicScene = () => (
40
  <pixiContainer x={100} y={100}>
41
    <pixiGraphics draw={(g) => { /* drawing code */ }} />
42
    <pixiText text="Hello World!" />
43
  </pixiContainer>
44
);
45

46
// Advanced component registration
47
extend({
48
  Sprite,
49
  TilingSprite,
50
  ParticleContainer,
51
});
52

53
const AdvancedScene = () => (
54
  <pixiContainer>
55
    <pixiSprite texture={myTexture} x={50} y={50} />
56
    <pixiTilingSprite 
57
      texture={tileTexture} 
58
      width={200} 
59
      height={200} 
60
      tileScale={{ x: 0.5, y: 0.5 }}
61
    />
62
    <pixiParticleContainer maxSize={1000}>
63
      {/* particle sprites */}
64
    </pixiParticleContainer>
65
  </pixiContainer>
66
);
67
```
68

69
### Component Naming Convention
70

71
Extended components are available as JSX elements with "pixi" prefix:
72

73
```typescript
74
extend({ Container }); // Available as <pixiContainer>
75
extend({ Graphics }); // Available as <pixiGraphics>
76
extend({ Text }); // Available as <pixiText>
77
extend({ BitmapText }); // Available as <pixiBitmapText>
78
```
79

80
Special naming overrides for HTML-prefixed components:
81

82
```typescript
83
extend({ HTMLText }); // Available as <pixiHtmlText> (not <pixiHTMLText>)
84
extend({ HTMLTextStyle }); // Available as <pixiHtmlTextStyle>
85
```
86

87
### Batch Extension
88

89
Register multiple components efficiently:
90

91
```typescript
92
import * as PIXI from "pixi.js";
93

94
// Register common display objects
95
extend({
96
  Container: PIXI.Container,
97
  Graphics: PIXI.Graphics,
98
  Text: PIXI.Text,
99
  Sprite: PIXI.Sprite,
100
  AnimatedSprite: PIXI.AnimatedSprite,
101
});
102

103
// Register mesh components
104
extend({
105
  Mesh: PIXI.Mesh,
106
  PlaneGeometry: PIXI.PlaneGeometry,
107
  MeshMaterial: PIXI.MeshMaterial,
108
});
109

110
// Register filter components
111
extend({
112
  BlurFilter: PIXI.BlurFilter,
113
  ColorMatrixFilter: PIXI.ColorMatrixFilter,
114
  DisplacementFilter: PIXI.DisplacementFilter,
115
});
116
```
117

118
### Custom Component Registration
119

120
Register custom PixiJS classes:
121

122
```typescript
123
import { extend } from "@pixi/react";
124
import { Container } from "pixi.js";
125

126
// Custom PixiJS class
127
class CustomSprite extends Container {
128
  constructor(options = {}) {
129
    super();
130
    // Custom initialization
131
    this.customProperty = options.customValue;
132
  }
133

134
  customMethod() {
135
    // Custom functionality
136
  }
137
}
138

139
// Register custom component
140
extend({ CustomSprite });
141

142
// Use in JSX
143
const CustomScene = () => (
144
  <pixiContainer>
145
    <pixiCustomSprite customValue="test" x={100} y={100} />
146
  </pixiContainer>
147
);
148
```
149

150
### Third-Party Plugin Integration
151

152
Register components from PixiJS plugins and extensions:
153

154
```typescript
155
import { extend } from "@pixi/react";
156
import { Spine } from "pixi-spine";
157
import { Live2DModel } from "pixi-live2d-display";
158
import { Viewport } from "pixi-viewport";
159

160
// Register plugin components
161
extend({
162
  Spine,
163
  Live2DModel,
164
  Viewport,
165
});
166

167
const PluginScene = () => (
168
  <pixiContainer>
169
    <pixiViewport 
170
      screenWidth={800} 
171
      screenHeight={600}
172
      worldWidth={1200}
173
      worldHeight={900}
174
    >
175
      <pixiSpine 
176
        spineData={spineData}
177
        x={400}
178
        y={300}
179
      />
180
      <pixiLive2DModel 
181
        modelUrl="model.model3.json"
182
        x={200}
183
        y={200}
184
      />
185
    </pixiViewport>
186
  </pixiContainer>
187
);
188
```
189

190
### Dynamic Extension
191

192
Components can be extended dynamically during runtime:
193

194
```typescript
195
import { extend } from "@pixi/react";
196
import { useState, useEffect } from "react";
197

198
const DynamicExtensionExample = () => {
199
  const [isExtended, setIsExtended] = useState(false);
200

201
  useEffect(() => {
202
    // Dynamically load and extend components
203
    import("pixi.js").then(({ NineSlicePlane, SimplePlane }) => {
204
      extend({ NineSlicePlane, SimplePlane });
205
      setIsExtended(true);
206
    });
207
  }, []);
208

209
  if (!isExtended) {
210
    return <pixiText text="Loading components..." />;
211
  }
212

213
  return (
214
    <pixiContainer>
215
      <pixiNineSlicePlane 
216
        texture={texture}
217
        leftWidth={10}
218
        topHeight={10}
219
        rightWidth={10}
220
        bottomHeight={10}
221
      />
222
    </pixiContainer>
223
  );
224
};
225
```
226

227
### Type Safety
228

229
Extended components maintain full TypeScript support:
230

231
```typescript
232
import { extend } from "@pixi/react";
233
import { Graphics, Container } from "pixi.js";
234

235
extend({ Graphics, Container });
236

237
// TypeScript will provide full type checking and autocomplete
238
const TypeSafeScene = () => (
239
  <pixiContainer
240
    x={100}        // ✓ Valid Container property
241
    y={100}        // ✓ Valid Container property
242
    alpha={0.5}    // ✓ Valid Container property
243
    // invalidProp={true} // ✗ TypeScript error
244
  >
245
    <pixiGraphics
246
      draw={(graphics) => {
247
        // Full Graphics API available with type checking
248
        graphics.setFillStyle({ color: "red" });
249
        graphics.rect(0, 0, 100, 100);
250
        graphics.fill();
251
      }}
252
      interactive={true}
253
      onPointerDown={(event) => {
254
        // Event is properly typed
255
        console.log(event.global.x, event.global.y);
256
      }}
257
    />
258
  </pixiContainer>
259
);
260
```
261

262
## Error Handling
263

264
The extend function includes validation and error handling:
265

266
- Validates that provided objects are constructor functions
267
- Warns about overriding existing component registrations
268
- Provides meaningful error messages for invalid component types
269
- Handles edge cases with malformed component objects