0
# Root Creation
1

2
The createRoot function provides an imperative API for creating PixiJS React roots, offering more control over application lifecycle and integration with existing applications.
3

4
## Capabilities
5

6
### Create Root Function
7

8
Creates a new root for a PixiJS React application with programmatic control.
9

10
```typescript { .api }
11
/**
12
 * Creates a new root for a Pixi React app
13
 * @param target - The DOM node which will serve as the root for this tree
14
 * @param options - Options to configure the tree
15
 * @returns Root instance for rendering PixiJS React components
16
 */
17
function createRoot(
18
  target: HTMLElement | HTMLCanvasElement,
19
  options?: CreateRootOptions
20
): Root;
21

22
interface CreateRootOptions {
23
  /** Callback to be fired when the application finishes initializing */
24
  onInit?: (app: PixiApplication) => void;
25
}
26

27
interface Root {
28
  /** 
29
   * Render PixiJS React components to the root
30
   * @param children - React components to render
31
   * @param applicationOptions - PixiJS application configuration
32
   * @returns Promise resolving to the PixiJS Application instance
33
   */
34
  render(children: ReactNode, applicationOptions: ApplicationOptions): Promise<PixiApplication>;
35
}
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import { createRoot, extend } from "@pixi/react";
42
import { Container, Graphics } from "pixi.js";
43
import React from "react";
44

45
extend({ Container, Graphics });
46

47
// Basic imperative usage
48
const ImperativeExample = async () => {
49
  const canvas = document.getElementById("pixi-canvas") as HTMLCanvasElement;
50
  
51
  const root = createRoot(canvas, {
52
    onInit: (app) => {
53
      console.log("PixiJS app initialized:", app);
54
    }
55
  });
56

57
  const app = await root.render(
58
    React.createElement("pixiContainer", { x: 100, y: 100 },
59
      React.createElement("pixiGraphics", {
60
        draw: (graphics) => {
61
          graphics.clear();
62
          graphics.setFillStyle({ color: "blue" });
63
          graphics.circle(0, 0, 50);
64
          graphics.fill();
65
        }
66
      })
67
    ),
68
    {
69
      width: 800,
70
      height: 600,
71
      backgroundColor: "0x1099bb"
72
    }
73
  );
74

75
  return app;
76
};
77

78
// Integration with existing DOM structure
79
const DOMIntegrationExample = () => {
80
  const initializePixi = async () => {
81
    const container = document.createElement("div");
82
    container.style.width = "100%";
83
    container.style.height = "400px";
84
    document.body.appendChild(container);
85

86
    const root = createRoot(container);
87
    
88
    await root.render(
89
      React.createElement("pixiContainer", {},
90
        React.createElement("pixiText", {
91
          text: "Dynamically created!",
92
          x: 200,
93
          y: 150,
94
          style: { fontSize: 24, fill: "white" }
95
        })
96
      ),
97
      { width: 800, height: 400 }
98
    );
99
  };
100

101
  return { initializePixi };
102
};
103

104
// Multiple roots management
105
const MultiRootExample = async () => {
106
  const canvas1 = document.getElementById("canvas-1") as HTMLCanvasElement;
107
  const canvas2 = document.getElementById("canvas-2") as HTMLCanvasElement;
108

109
  const root1 = createRoot(canvas1);
110
  const root2 = createRoot(canvas2);
111

112
  // Render different content to each root
113
  const [app1, app2] = await Promise.all([
114
    root1.render(
115
      React.createElement("pixiText", { text: "First App", x: 100, y: 100 }),
116
      { width: 400, height: 300, backgroundColor: "red" }
117
    ),
118
    root2.render(
119
      React.createElement("pixiText", { text: "Second App", x: 100, y: 100 }),
120
      { width: 400, height: 300, backgroundColor: "blue" }
121
    )
122
  ]);
123

124
  return { app1, app2 };
125
};
126
```
127

128
### Canvas vs Container Target
129

130
The createRoot function accepts both canvas elements and container elements:
131

132
```typescript
133
// Using existing canvas element
134
const canvasRoot = createRoot(
135
  document.getElementById("my-canvas") as HTMLCanvasElement
136
);
137

138
// Using container element (canvas will be created automatically)
139
const containerRoot = createRoot(
140
  document.getElementById("my-container") as HTMLDivElement
141
);
142
```
143

144
### Re-rendering
145

146
Roots can be re-rendered with different content or options:
147

148
```typescript
149
const root = createRoot(document.getElementById("canvas") as HTMLCanvasElement);
150

151
// Initial render
152
await root.render(
153
  React.createElement("pixiText", { text: "Hello", x: 100, y: 100 }),
154
  { width: 800, height: 600 }
155
);
156

157
// Re-render with different content
158
await root.render(
159
  React.createElement("pixiText", { text: "Updated!", x: 150, y: 150 }),
160
  { width: 800, height: 600, backgroundColor: "0x333333" }
161
);
162
```
163

164
### Application Options
165

166
All PixiJS ApplicationOptions are supported in the render method:
167

168
```typescript { .api }
169
interface ApplicationOptions {
170
  /** Canvas width in pixels */
171
  width?: number;
172
  /** Canvas height in pixels */
173
  height?: number;
174
  /** Background color of the canvas */
175
  backgroundColor?: ColorSource;
176
  /** Background alpha transparency */
177
  backgroundAlpha?: number;
178
  /** Enable antialiasing for smoother graphics */
179
  antialias?: boolean;
180
  /** Device pixel ratio for high-DPI displays */
181
  resolution?: number;
182
  /** Automatically adjust resolution based on device pixel ratio */
183
  autoDensity?: boolean;
184
  /** WebGL power preference */
185
  powerPreference?: WebGLPowerPreference;
186
  /** Enable premultiplied alpha */
187
  premultipliedAlpha?: boolean;
188
  /** Preserve drawing buffer for reading pixels */
189
  preserveDrawingBuffer?: boolean;
190
  /** Clear canvas before each render */
191
  clearBeforeRender?: boolean;
192
  /** Show PixiJS hello message in console */
193
  hello?: boolean;
194
}
195
```
196

197
## Error Handling
198

199
The createRoot function includes comprehensive error handling:
200

201
- Validates target element exists and is accessible
202
- Handles canvas creation failures
203
- Provides meaningful error messages for invalid configurations
204
- Manages cleanup when roots are no longer needed
205
- Prevents multiple roots on the same canvas element (logs warning)