0
# Text Rendering
1

2
Comprehensive text rendering system supporting canvas-based text, bitmap fonts, and HTML text with CSS styling. Includes font loading, text metrics, advanced text features, and multiple rendering approaches for different use cases.
3

4
## Capabilities
5

6
### Text Class
7

8
Canvas-based text rendering with advanced styling and layout options.
9

10
```typescript { .api }
11
/**
12
 * Canvas-based text rendering
13
 */
14
class Text extends Container {
15
  constructor(options?: TextOptions);
16
  
17
  /** Text content */
18
  text: string;
19
  
20
  /** Text style configuration */
21
  style: TextStyle;
22
  
23
  /** Text resolution for crisp rendering */
24
  resolution: number;
25
  
26
  /** Text width */
27
  readonly width: number;
28
  
29
  /** Text height */
30
  readonly height: number;
31
  
32
  /**
33
   * Get text metrics
34
   * @returns Text measurement data
35
   */
36
  getTextMetrics(): TextMetrics;
37
  
38
  /**
39
   * Update text and style
40
   * @param text - New text content
41
   * @param style - New text style
42
   * @returns This text instance
43
   */
44
  updateText(text?: string, style?: Partial<TextStyleOptions>): this;
45
}
46

47
interface TextOptions {
48
  /** Text content */
49
  text?: string;
50
  
51
  /** Text style */
52
  style?: Partial<TextStyleOptions>;
53
  
54
  /** Text resolution */
55
  resolution?: number;
56
}
57
```
58

59
### Text Style
60

61
Comprehensive text styling system with support for fonts, colors, shadows, and layout.
62

63
```typescript { .api }
64
/**
65
 * Text style configuration
66
 */
67
class TextStyle {
68
  constructor(style?: Partial<TextStyleOptions>);
69
  
70
  /** Font family */
71
  fontFamily: string | string[];
72
  
73
  /** Font size in pixels */
74
  fontSize: number;
75
  
76
  /** Font style */
77
  fontStyle: 'normal' | 'italic' | 'oblique';
78
  
79
  /** Font variant */
80
  fontVariant: 'normal' | 'small-caps';
81
  
82
  /** Font weight */
83
  fontWeight: 'normal' | 'bold' | 'bolder' | 'lighter' | number;
84
  
85
  /** Text color */
86
  fill: FillInput;
87
  
88
  /** Text stroke */
89
  stroke: StrokeInput;
90
  
91
  /** Stroke thickness */
92
  strokeThickness: number;
93
  
94
  /** Text alignment */
95
  align: 'left' | 'center' | 'right' | 'justify';
96
  
97
  /** Line height multiplier */
98
  lineHeight: number;
99
  
100
  /** Letter spacing in pixels */
101
  letterSpacing: number;
102
  
103
  /** Word wrap */
104
  wordWrap: boolean;
105
  
106
  /** Word wrap width */
107
  wordWrapWidth: number;
108
  
109
  /** Break words */
110
  breakWords: boolean;
111
  
112
  /** Text baseline */
113
  textBaseline: 'alphabetic' | 'top' | 'hanging' | 'middle' | 'ideographic' | 'bottom';
114
  
115
  /** Leading trim */
116
  leading: number;
117
  
118
  /** Drop shadow */
119
  dropShadow: DropShadowOptions;
120
  
121
  /** Padding */
122
  padding: number;
123
  
124
  /** Trim transparent pixels */
125
  trim: boolean;
126
  
127
  /**
128
   * Clone style
129
   * @returns Cloned text style
130
   */
131
  clone(): TextStyle;
132
  
133
  /**
134
   * Reset style to defaults
135
   */
136
  reset(): void;
137
  
138
  /**
139
   * Generate font string
140
   * @returns CSS font string
141
   */
142
  toFontString(): string;
143
}
144

145
interface TextStyleOptions {
146
  fontFamily: string | string[];
147
  fontSize: number;
148
  fontStyle: 'normal' | 'italic' | 'oblique';
149
  fontVariant: 'normal' | 'small-caps';
150
  fontWeight: 'normal' | 'bold' | 'bolder' | 'lighter' | number;
151
  fill: FillInput;
152
  stroke: StrokeInput;
153
  strokeThickness: number;
154
  align: 'left' | 'center' | 'right' | 'justify';
155
  lineHeight: number;
156
  letterSpacing: number;
157
  wordWrap: boolean;
158
  wordWrapWidth: number;
159
  breakWords: boolean;
160
  textBaseline: 'alphabetic' | 'top' | 'hanging' | 'middle' | 'ideographic' | 'bottom';
161
  leading: number;
162
  dropShadow: DropShadowOptions;
163
  padding: number;
164
  trim: boolean;
165
}
166

167
interface DropShadowOptions {
168
  /** Enable drop shadow */
169
  alpha: number;
170
  
171
  /** Shadow angle in radians */
172
  angle: number;
173
  
174
  /** Shadow blur */
175
  blur: number;
176
  
177
  /** Shadow color */
178
  color: ColorSource;
179
  
180
  /** Shadow distance */
181
  distance: number;
182
}
183
```
184

185
### Bitmap Text
186

187
Bitmap font text rendering for crisp, scalable text using pre-rendered character textures.
188

189
```typescript { .api }
190
/**
191
 * Bitmap font text rendering  
192
 */
193
class BitmapText extends Container {
194
  constructor(options?: BitmapTextOptions);
195
  
196
  /** Text content */
197
  text: string;
198
  
199
  /** Bitmap font to use */
200
  style: BitmapTextStyle;
201
  
202
  /** Text width */
203
  readonly textWidth: number;
204
  
205
  /** Text height */
206
  readonly textHeight: number;
207
  
208
  /** Font size */
209
  fontSize: number;
210
  
211
  /** Text alignment */
212
  align: 'left' | 'center' | 'right';
213
  
214
  /** Tint color */
215
  tint: ColorSource;
216
  
217
  /** Letter spacing */
218
  letterSpacing: number;
219
  
220
  /** Max width for wrapping */
221
  maxWidth: number;
222
  
223
  /** Max height for clipping */
224
  maxHeight: number;
225
  
226
  /** Text anchor point */
227
  anchor: ObservablePoint;
228
  
229
  /** Enable rounding positions */
230
  roundPixels: boolean;
231
  
232
  /**
233
   * Get local bounds
234
   * @param rect - Rectangle to store bounds
235
   * @returns Text bounds
236
   */
237
  getLocalBounds(rect?: Rectangle): Rectangle;
238
  
239
  /**
240
   * Update text
241
   * @param text - New text content
242
   * @returns This bitmap text
243
   */
244
  updateText(text?: string): this;
245
}
246

247
interface BitmapTextOptions {
248
  /** Text content */
249
  text?: string;
250
  
251
  /** Bitmap text style */
252
  style?: BitmapTextStyle;
253
}
254

255
interface BitmapTextStyle {
256
  /** Font family/name */
257
  fontFamily: string;
258
  
259
  /** Font size */
260
  fontSize: number;
261
  
262
  /** Text alignment */
263
  align: 'left' | 'center' | 'right';
264
  
265
  /** Tint color */
266
  tint: ColorSource;
267
  
268
  /** Letter spacing */
269
  letterSpacing: number;
270
  
271
  /** Line height */
272
  lineHeight: number;
273
}
274
```
275

276
### HTML Text
277

278
HTML-based text rendering with CSS styling support for rich text layouts.
279

280
```typescript { .api }
281
/**
282
 * HTML text rendering with CSS styling
283
 */
284
class HTMLText extends Container {
285
  constructor(options?: HTMLTextOptions);
286
  
287
  /** HTML text content */
288
  text: string;
289
  
290
  /** HTML text style */
291
  style: HTMLTextStyle;
292
  
293
  /** Text width */
294
  readonly width: number;
295
  
296
  /** Text height */
297
  readonly height: number;
298
  
299
  /** Text resolution */
300
  resolution: number;
301
  
302
  /**
303
   * Update text content
304
   * @param text - New HTML text
305
   * @returns This HTML text
306
   */
307
  updateText(text?: string): this;
308
}
309

310
interface HTMLTextOptions {
311
  /** HTML text content */
312
  text?: string;
313
  
314
  /** HTML text style */
315
  style?: Partial<HTMLTextStyleOptions>;
316
}
317

318
/**
319
 * HTML text style with CSS properties
320
 */
321
class HTMLTextStyle {
322
  constructor(style?: Partial<HTMLTextStyleOptions>);
323
  
324
  /** Font family */
325
  fontFamily: string;
326
  
327
  /** Font size */
328
  fontSize: number | string;
329
  
330
  /** Font style */
331
  fontStyle: string;
332
  
333
  /** Font weight */
334
  fontWeight: string;
335
  
336
  /** Text color */
337
  fill: ColorSource;
338
  
339
  /** Text alignment */
340
  align: string;
341
  
342
  /** Vertical alignment */
343
  valign: string;
344
  
345
  /** Word wrap */
346
  wordWrap: boolean;
347
  
348
  /** Word wrap width */
349
  wordWrapWidth: number;
350
  
351
  /** Line height */
352
  lineHeight: number;
353
  
354
  /** Padding */
355
  padding: number;
356
  
357
  /**
358
   * Clone style
359
   * @returns Cloned HTML text style
360
   */
361
  clone(): HTMLTextStyle;
362
}
363

364
interface HTMLTextStyleOptions {
365
  fontFamily: string;
366
  fontSize: number | string;
367
  fontStyle: string;
368
  fontWeight: string;
369
  fill: ColorSource;
370
  align: string;
371
  valign: string;
372
  wordWrap: boolean;
373
  wordWrapWidth: number;
374
  lineHeight: number;
375
  padding: number;
376
}
377
```
378

379
### Bitmap Font Management
380

381
Bitmap font loading and management system.
382

383
```typescript { .api }
384
/**
385
 * Bitmap font resource
386
 */
387
class BitmapFont {
388
  constructor(data: BitmapFontData, textures: Texture[]);
389
  
390
  /** Font information */
391
  info: BitmapFontInfo;
392
  
393
  /** Common font properties */
394
  common: BitmapFontCommon;
395
  
396
  /** Font pages/textures */
397
  pages: Texture[];
398
  
399
  /** Character data */
400
  chars: Record<number, BitmapFontChar>;
401
  
402
  /** Kerning pairs */
403
  kernings: Record<string, number>;
404
  
405
  /** Distance field properties */
406
  distanceField: BitmapFontDistanceField;
407
  
408
  /**
409
   * Get character data
410
   * @param char - Character code
411
   * @returns Character data
412
   */
413
  getChar(char: number): BitmapFontChar;
414
  
415
  /**
416
   * Get kerning between characters
417
   * @param first - First character
418
   * @param second - Second character
419
   * @returns Kerning amount
420
   */
421
  getKerning(first: number, second: number): number;
422
}
423

424
/**
425
 * Dynamic bitmap font for runtime text generation
426
 */
427
class DynamicBitmapFont extends BitmapFont {
428
  constructor(name: string, style: TextStyle, options?: DynamicBitmapFontOptions);
429
  
430
  /** Font name */
431
  fontName: string;
432
  
433
  /** Text style used */
434
  style: TextStyle;
435
  
436
  /** Resolution */
437
  resolution: number;
438
  
439
  /** Padding */
440
  padding: number;
441
  
442
  /**
443
   * Update font with new characters
444
   * @param chars - Characters to add
445
   */
446
  updateChars(chars: string): void;
447
}
448

449
interface BitmapFontData {
450
  info: BitmapFontInfo;
451
  common: BitmapFontCommon;
452
  pages: string[];
453
  chars: BitmapFontChar[];
454
  kernings?: BitmapFontKerning[];
455
  distanceField?: BitmapFontDistanceField;
456
}
457

458
interface BitmapFontInfo {
459
  face: string;
460
  size: number;
461
  bold: boolean;
462
  italic: boolean;
463
  charset: string;
464
  unicode: boolean;
465
  stretchH: number;
466
  smooth: boolean;
467
  aa: number;
468
  padding: [number, number, number, number];
469
  spacing: [number, number];
470
}
471

472
interface BitmapFontCommon {
473
  lineHeight: number;
474
  base: number;
475
  scaleW: number;
476
  scaleH: number;
477
  pages: number;
478
  packed: boolean;
479
}
480

481
interface BitmapFontChar {
482
  id: number;
483
  page: number;
484
  x: number;
485
  y: number;
486
  width: number;
487
  height: number;
488
  xoffset: number;
489
  yoffset: number;
490
  xadvance: number;
491
  chnl: number;
492
}
493
```
494

495
### Text Metrics
496

497
Text measurement and layout utilities.
498

499
```typescript { .api }
500
/**
501
 * Text metrics for measuring text
502
 */
503
interface TextMetrics {
504
  /** Text content */
505
  text: string;
506
  
507
  /** Text style */
508
  style: TextStyle;
509
  
510
  /** Text width */
511
  width: number;
512
  
513
  /** Text height */
514
  height: number;
515
  
516
  /** Text lines */
517
  lines: string[];
518
  
519
  /** Line widths */
520
  lineWidths: number[];
521
  
522
  /** Line height */
523
  lineHeight: number;
524
  
525
  /** Max line width */
526
  maxLineWidth: number;
527
  
528
  /** Font properties */
529
  fontProperties: FontMetrics;
530
}
531

532
interface FontMetrics {
533
  /** Ascent */
534
  ascent: number;
535
  
536
  /** Descent */
537
  descent: number;
538
  
539
  /** Font size */
540
  fontSize: number;
541
}
542

543
/**
544
 * Canvas text metrics utility
545
 */
546
class CanvasTextMetrics {
547
  /**
548
   * Measure text with given style
549
   * @param text - Text to measure
550
   * @param style - Text style
551
   * @param wordWrap - Enable word wrapping
552
   * @param canvas - Canvas to use for measurement
553
   * @returns Text metrics
554
   */
555
  static measureText(text: string, style: TextStyle, wordWrap?: boolean, canvas?: HTMLCanvasElement): TextMetrics;
556
  
557
  /**
558
   * Get font metrics
559
   * @param font - Font string
560
   * @returns Font metrics
561
   */
562
  static measureFont(font: string): FontMetrics;
563
}
564
```
565

566
**Usage Examples:**
567

568
```typescript
569
import { Text, BitmapText, HTMLText, TextStyle, Assets } from 'pixi.js';
570

571
// Basic text
572
const text = new Text({
573
  text: 'Hello PixiJS!',
574
  style: {
575
    fontSize: 32,
576
    fill: 0xffffff,
577
    fontFamily: 'Arial'
578
  }
579
});
580

581
// Advanced text styling
582
const styledText = new Text({
583
  text: 'Styled Text with\nMultiple Lines',
584
  style: {
585
    fontSize: 24,
586
    fontFamily: ['Helvetica', 'Arial', 'sans-serif'],
587
    fill: ['#ff0000', '#00ff00'], // Gradient fill
588
    stroke: 0x000000,
589
    strokeThickness: 2,
590
    dropShadow: {
591
      color: 0x000000,
592
      blur: 4,
593
      angle: Math.PI / 6,
594
      distance: 6
595
    },
596
    wordWrap: true,
597
    wordWrapWidth: 200,
598
    align: 'center',
599
    lineHeight: 1.2
600
  }
601
});
602

603
// Bitmap text
604
await Assets.load('bitmap-font.fnt');
605
const bitmapText = new BitmapText({
606
  text: 'Bitmap Text',
607
  style: {
608
    fontFamily: 'MyBitmapFont',
609
    fontSize: 32,
610
    tint: 0xff0000
611
  }
612
});
613

614
// HTML text with rich formatting
615
const htmlText = new HTMLText({
616
  text: '<b>Bold</b> and <i>italic</i> text with <span style="color: red;">colored</span> words',
617
  style: {
618
    fontSize: 18,
619
    fontFamily: 'Arial',
620
    fill: 0x000000,
621
    wordWrap: true,
622
    wordWrapWidth: 300
623
  }
624
});
625

626
// Dynamic text updates
627
let counter = 0;
628
app.ticker.add(() => {
629
  text.text = `Counter: ${counter++}`;
630
});
631

632
// Text with custom fonts
633
Assets.add({ alias: 'customFont', src: 'fonts/CustomFont.woff2' });
634
await Assets.load('customFont');
635

636
const customText = new Text({
637
  text: 'Custom Font Text',
638
  style: {
639
    fontFamily: 'CustomFont',
640
    fontSize: 28,
641
    fill: 0x00ff00
642
  }
643
});
644

645
// Text metrics and measurement
646
const metrics = text.getTextMetrics();
647
console.log(`Text size: ${metrics.width}x${metrics.height}`);
648

649
// Interactive text
650
text.interactive = true;
651
text.buttonMode = true;
652
text.on('pointerdown', () => {
653
  text.style.fill = Math.random() * 0xffffff;
654
});
655

656
// Bitmap font with distance fields for crisp scaling
657
const sdfText = new BitmapText({
658
  text: 'Scalable Text',
659
  style: {
660
    fontFamily: 'SDFFont',
661
    fontSize: 64
662
  }
663
});
664
sdfText.scale.set(0.5); // Scales cleanly with SDF fonts
665
```