0
# Text Rendering
1

2
Core text rendering functionality for creating and managing text objects that integrate seamlessly with the PixiJS display hierarchy. The Text class extends Sprite to render text as textures using the Canvas API with automatic texture generation and WebGL integration.
3

4
## Capabilities
5

6
### Text Constructor
7

8
Creates a new Text object with optional initial content, styling, and canvas.
9

10
```typescript { .api }
11
/**
12
 * Creates a Text object that renders text using Canvas API
13
 * @param text - Initial text content (string or number)
14
 * @param style - Text styling configuration
15
 * @param canvas - Optional canvas element for rendering
16
 */
17
constructor(text?: string | number, style?: Partial<ITextStyle> | TextStyle, canvas?: HTMLCanvasElement);
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { Text, TextStyle } from "@pixi/text";
24

25
// Simple text creation
26
const text1 = new Text('Hello World');
27

28
// Text with inline style
29
const text2 = new Text('Styled Text', {
30
  fontSize: 24,
31
  fill: 0xff0000,
32
  fontFamily: 'Arial'
33
});
34

35
// Text with TextStyle object
36
const style = new TextStyle({ fontSize: 32, fill: 'blue' });
37
const text3 = new Text('Blue Text', style);
38

39
// Text with custom canvas
40
const canvas = document.createElement('canvas');
41
const text4 = new Text('Custom Canvas', style, canvas);
42
```
43

44
### Text Content Management
45

46
Manages the text content string with automatic re-rendering when changed.
47

48
```typescript { .api }
49
/**
50
 * The text content to display
51
 * Setting this property marks the text as dirty for re-rendering
52
 */
53
text: string;
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
const text = new Text('Initial text');
60

61
// Update text content
62
text.text = 'New content';
63

64
// Text is automatically re-rendered when displayed
65
```
66

67
### Style Management
68

69
Controls the visual appearance of the text through TextStyle objects or style literals.
70

71
```typescript { .api }
72
/**
73
 * The text style configuration
74
 * Can be a TextStyle object or a partial style configuration
75
 */
76
style: TextStyle | Partial<ITextStyle>;
77
```
78

79
**Usage Examples:**
80

81
```typescript
82
const text = new Text('Sample text');
83

84
// Update with style object
85
const newStyle = new TextStyle({
86
  fontSize: 28,
87
  fill: '#ff6600'
88
});
89
text.style = newStyle;
90

91
// Update with partial style
92
text.style = {
93
  fontSize: 32,
94
  fontFamily: 'Helvetica',
95
  fill: 0x00ff00
96
};
97
```
98

99
### Resolution Control
100

101
Manages the rendering resolution for crisp text display on different devices.
102

103
```typescript { .api }
104
/**
105
 * The resolution/device pixel ratio for text rendering
106
 * Automatically matches renderer resolution by default
107
 * @default settings.RESOLUTION
108
 */
109
resolution: number;
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
const text = new Text('High DPI Text');
116

117
// Set custom resolution for high-DPI displays
118
text.resolution = 2;
119

120
// Get current resolution
121
console.log(text.resolution);
122
```
123

124
### Manual Text Updates
125

126
Forces text re-rendering and texture updates when needed.
127

128
```typescript { .api }
129
/**
130
 * Renders text to canvas and updates texture
131
 * @param respectDirty - Whether to skip update if text isn't dirty
132
 */
133
updateText(respectDirty: boolean): void;
134
```
135

136
**Usage Examples:**
137

138
```typescript
139
const text = new Text('Manual Update');
140

141
// Force text update regardless of dirty state
142
text.updateText(false);
143

144
// Update only if text is dirty
145
text.updateText(true);
146
```
147

148
### Size Properties
149

150
Width and height properties that modify the text scale to achieve desired dimensions.
151

152
```typescript { .api }
153
/**
154
 * Text width - setting this modifies the scale to achieve the target width
155
 */
156
width: number;
157

158
/**
159
 * Text height - setting this modifies the scale to achieve the target height  
160
 */
161
height: number;
162
```
163

164
**Usage Examples:**
165

166
```typescript
167
const text = new Text('Scalable Text');
168

169
// Set specific dimensions
170
text.width = 300;
171
text.height = 100;
172

173
// Get current dimensions
174
console.log(`Size: ${text.width}x${text.height}`);
175
```
176

177
### Resource Management
178

179
Proper cleanup of text resources including canvas and textures.
180

181
```typescript { .api }
182
/**
183
 * Destroys the text object and cleans up resources
184
 * @param options - Destruction options or boolean for children
185
 */
186
destroy(options?: IDestroyOptions | boolean): void;
187

188
interface IDestroyOptions {
189
  children?: boolean;
190
  texture?: boolean;
191
  baseTexture?: boolean;
192
}
193
```
194

195
**Usage Examples:**
196

197
```typescript
198
const text = new Text('Temporary text');
199

200
// Clean destroy with default options
201
text.destroy();
202

203
// Destroy with specific options
204
text.destroy({
205
  children: false,
206
  texture: true,
207
  baseTexture: true
208
});
209

210
// Destroy children only
211
text.destroy(true);
212
```
213

214
### Static Configuration
215

216
Global configuration options that affect all Text instances.
217

218
```typescript { .api }
219
/**
220
 * Global flag for new line height behavior
221
 * Controls HTML-like line height rendering
222
 */
223
static nextLineHeightBehavior: boolean;
224

225
/**
226
 * Global flag for experimental letter spacing
227
 * Enables Chrome's native letter-spacing API when available
228
 */
229
static experimentalLetterSpacing: boolean;
230
```
231

232
**Usage Examples:**
233

234
```typescript
235
// Enable new line height behavior globally
236
Text.nextLineHeightBehavior = true;
237

238
// Enable experimental letter spacing
239
Text.experimentalLetterSpacing = true;
240
```
241

242
### Bounds and Transform Updates
243

244
Methods for updating bounds and transforms with text re-rendering.
245

246
```typescript { .api }
247
/**
248
 * Updates transform and ensures text is current
249
 */
250
updateTransform(): void;
251

252
/**
253
 * Gets bounds with text update
254
 * @param skipUpdate - Whether to skip transform update
255
 * @param rect - Optional rectangle to store result
256
 */
257
getBounds(skipUpdate?: boolean, rect?: Rectangle): Rectangle;
258

259
/**
260
 * Gets local bounds with text update
261
 * @param rect - Optional rectangle to store result
262
 */
263
getLocalBounds(rect?: Rectangle): Rectangle;
264
```
265

266
**Usage Examples:**
267

268
```typescript
269
const text = new Text('Bounds Test');
270

271
// Update transform
272
text.updateTransform();
273

274
// Get bounds
275
const bounds = text.getBounds();
276
console.log(`Bounds: ${bounds.width}x${bounds.height}`);
277

278
// Get local bounds
279
const localBounds = text.getLocalBounds();
280
```
281

282
## Canvas and Context Access
283

284
Direct access to the underlying canvas and rendering context for advanced use cases.
285

286
```typescript { .api }
287
/**
288
 * The canvas element used for text rendering
289
 */
290
canvas: HTMLCanvasElement;
291

292
/**
293
 * The 2D rendering context for the canvas
294
 */
295
context: CanvasRenderingContext2D;
296
```
297

298
**Usage Examples:**
299

300
```typescript
301
const text = new Text('Canvas Access');
302

303
// Access canvas properties
304
console.log(`Canvas size: ${text.canvas.width}x${text.canvas.height}`);
305

306
// Access context for custom drawing (advanced)
307
const ctx = text.context;
308
ctx.globalAlpha = 0.5;
309
```
310

311
## Integration with PixiJS
312

313
Text objects integrate fully with the PixiJS display system as Sprites with texture-based rendering.
314

315
**Usage Examples:**
316

317
```typescript
318
import { Application } from "@pixi/app";
319
import { Text } from "@pixi/text";
320

321
const app = new Application();
322
const text = new Text('PixiJS Integration');
323

324
// Add to display hierarchy
325
app.stage.addChild(text);
326

327
// Position like any display object
328
text.x = 100;
329
text.y = 50;
330

331
// Apply transforms
332
text.rotation = Math.PI / 4;
333
text.scale.set(1.5);
334
```