0
# @pixi/text
1

2
@pixi/text is a TypeScript library that provides comprehensive text rendering capabilities for the PixiJS graphics library using the Canvas API. It enables developers to create and style text objects with full control over typography, including fonts, colors, gradients, shadows, alignment, and advanced features like word wrapping and letter spacing.
3

4
## Package Information
5

6
- **Package Name**: @pixi/text
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @pixi/text`
10

11
## Core Imports
12

13
```typescript
14
import { Text, TextStyle, TextMetrics, TEXT_GRADIENT } from "@pixi/text";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Text, TextStyle, TextMetrics, TEXT_GRADIENT } = require("@pixi/text");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { Text, TextStyle } from "@pixi/text";
27

28
// Create a styled text object
29
const style = new TextStyle({
30
  fontFamily: 'Arial',
31
  fontSize: 36,
32
  fill: '#ffffff',
33
  stroke: '#000000',
34
  strokeThickness: 4,
35
  dropShadow: true,
36
  dropShadowColor: '#000000',
37
  dropShadowBlur: 4,
38
  dropShadowAngle: Math.PI / 6,
39
  dropShadowDistance: 6,
40
  wordWrap: true,
41
  wordWrapWidth: 440
42
});
43

44
const text = new Text('Hello, PixiJS!', style);
45

46
// Update text content
47
text.text = 'Updated text content';
48

49
// Measure text dimensions
50
const metrics = TextMetrics.measureText('Sample text', style);
51
console.log(`Text dimensions: ${metrics.width}x${metrics.height}`);
52
```
53

54
## Architecture
55

56
@pixi/text is built around three core components:
57

58
- **Text Class**: Extends PixiJS Sprite to render text as textures using Canvas API, with automatic texture generation and WebGL integration
59
- **TextStyle System**: Comprehensive styling configuration with property change tracking and efficient updates
60
- **TextMetrics Engine**: Advanced text measurement system with font metrics calculation, word wrapping, and character-level analysis
61
- **Canvas Integration**: Direct Canvas API usage for text rendering with support for gradients, shadows, and complex typography
62

63
## Capabilities
64

65
### Text Rendering
66

67
Core text rendering functionality for creating and managing text objects that integrate seamlessly with the PixiJS display hierarchy.
68

69
```typescript { .api }
70
class Text extends Sprite {
71
  constructor(text?: string | number, style?: Partial<ITextStyle> | TextStyle, canvas?: HTMLCanvasElement);
72
  
73
  // Static properties
74
  static nextLineHeightBehavior: boolean;
75
  static experimentalLetterSpacing: boolean;
76
  
77
  // Instance properties
78
  text: string;
79
  style: TextStyle | Partial<ITextStyle>;
80
  resolution: number;
81
  width: number;
82
  height: number;
83
  canvas: HTMLCanvasElement;
84
  context: CanvasRenderingContext2D;
85
  localStyleID: number;
86
  dirty: boolean;
87
  
88
  // Methods
89
  updateText(respectDirty: boolean): void;
90
  updateTransform(): void;
91
  getBounds(skipUpdate?: boolean, rect?: Rectangle): Rectangle;
92
  getLocalBounds(rect?: Rectangle): Rectangle;
93
  destroy(options?: IDestroyOptions | boolean): void;
94
}
95
```
96

97
[Text Rendering](./text-rendering.md)
98

99
### Text Styling
100

101
Comprehensive text styling system with real-time property updates and extensive typography controls including fonts, colors, gradients, shadows, and layout options.
102

103
```typescript { .api }
104
class TextStyle implements ITextStyle {
105
  constructor(style?: Partial<ITextStyle>);
106
  
107
  // Typography
108
  fontFamily: string | string[];
109
  fontSize: number | string;
110
  fontStyle: TextStyleFontStyle;
111
  fontWeight: TextStyleFontWeight;
112
  
113
  // Colors and Effects
114
  fill: TextStyleFill;
115
  stroke: string | number;
116
  strokeThickness: number;
117
  dropShadow: boolean;
118
  
119
  // Layout
120
  align: TextStyleAlign;
121
  wordWrap: boolean;
122
  wordWrapWidth: number;
123
  
124
  clone(): TextStyle;
125
  reset(): void;
126
  toFontString(): string;
127
}
128
```
129

130
[Text Styling](./text-styling.md)
131

132
### Text Measurement
133

134
Advanced text measurement utilities for calculating dimensions, font properties, and text layout with support for word wrapping and multi-line text analysis.
135

136
```typescript { .api }
137
class TextMetrics {
138
  constructor(text: string, style: TextStyle, width: number, height: number, 
139
              lines: string[], lineWidths: number[], lineHeight: number, 
140
              maxLineWidth: number, fontProperties: IFontMetrics);
141
  
142
  // Static methods
143
  static measureText(text: string, style: TextStyle, wordWrap?: boolean, 
144
                     canvas?: HTMLCanvasElement | OffscreenCanvas): TextMetrics;
145
  static measureFont(font: string): IFontMetrics;
146
  static clearMetrics(font?: string): void;
147
  static isBreakingSpace(char: string, nextChar?: string): boolean;
148
  static canBreakWords(token: string, breakWords: boolean): boolean;
149
  static canBreakChars(char: string, nextChar: string, token: string, index: number, breakWords: boolean): boolean;
150
  static wordWrapSplit(token: string): string[];
151
  
152
  // Static properties
153
  static METRICS_STRING: string;
154
  static BASELINE_SYMBOL: string;
155
  static BASELINE_MULTIPLIER: number;
156
  static HEIGHT_MULTIPLIER: number;
157
  static get _canvas(): HTMLCanvasElement | OffscreenCanvas;
158
  static get _context(): CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
159
  
160
  // Instance properties
161
  text: string;
162
  style: TextStyle;
163
  width: number;
164
  height: number;
165
  lines: string[];
166
  lineWidths: number[];
167
  lineHeight: number;
168
  maxLineWidth: number;
169
  fontProperties: IFontMetrics;
170
}
171
```
172

173
[Text Measurement](./text-measurement.md)
174

175
## Types
176

177
```typescript { .api }
178
// Core interfaces
179
interface ITextStyle {
180
  align: TextStyleAlign;
181
  breakWords: boolean;
182
  dropShadow: boolean;
183
  dropShadowAlpha: number;
184
  dropShadowAngle: number;
185
  dropShadowBlur: number;
186
  dropShadowColor: string | number;
187
  dropShadowDistance: number;
188
  fill: TextStyleFill;
189
  fillGradientType: TEXT_GRADIENT;
190
  fillGradientStops: number[];
191
  fontFamily: string | string[];
192
  fontSize: number | string;
193
  fontStyle: TextStyleFontStyle;
194
  fontVariant: TextStyleFontVariant;
195
  fontWeight: TextStyleFontWeight;
196
  letterSpacing: number;
197
  lineHeight: number;
198
  lineJoin: TextStyleLineJoin;
199
  miterLimit: number;
200
  padding: number;
201
  stroke: string | number;
202
  strokeThickness: number;
203
  textBaseline: TextStyleTextBaseline;
204
  trim: boolean;
205
  whiteSpace: TextStyleWhiteSpace;
206
  wordWrap: boolean;
207
  wordWrapWidth: number;
208
  leading: number;
209
}
210

211
interface IFontMetrics {
212
  ascent: number;
213
  descent: number;
214
  fontSize: number;
215
}
216

217
interface IDestroyOptions {
218
  children?: boolean;
219
  texture?: boolean;
220
  baseTexture?: boolean;
221
}
222

223
// Rectangle from @pixi/math
224
interface Rectangle {
225
  x: number;
226
  y: number;
227
  width: number;
228
  height: number;
229
}
230

231
// Type unions
232
type TextStyleAlign = 'left' | 'center' | 'right' | 'justify';
233
type TextStyleFill = string | string[] | number | number[] | CanvasGradient | CanvasPattern;
234
type TextStyleFontStyle = 'normal' | 'italic' | 'oblique';
235
type TextStyleFontVariant = 'normal' | 'small-caps';
236
type TextStyleFontWeight = 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
237
type TextStyleLineJoin = 'miter' | 'round' | 'bevel';
238
type TextStyleTextBaseline = 'alphabetic' | 'top' | 'hanging' | 'middle' | 'ideographic' | 'bottom';
239
type TextStyleWhiteSpace = 'normal' | 'pre' | 'pre-line';
240

241
// Constants
242
enum TEXT_GRADIENT {
243
  LINEAR_VERTICAL = 0,
244
  LINEAR_HORIZONTAL = 1
245
}
246
```