0
# Text Styling
1

2
Comprehensive text styling system with real-time property updates and extensive typography controls. The TextStyle class provides fine-grained control over font properties, colors, effects, and layout with efficient change tracking.
3

4
## Capabilities
5

6
### TextStyle Constructor
7

8
Creates a new TextStyle object with optional initial style configuration.
9

10
```typescript { .api }
11
/**
12
 * Creates a TextStyle with specified properties
13
 * @param style - Partial style configuration object
14
 */
15
constructor(style?: Partial<ITextStyle>);
16
```
17

18
**Usage Examples:**
19

20
```typescript
21
import { TextStyle, TEXT_GRADIENT } from "@pixi/text";
22

23
// Create with default style
24
const defaultStyle = new TextStyle();
25

26
// Create with custom properties
27
const customStyle = new TextStyle({
28
  fontFamily: 'Arial',
29
  fontSize: 24,
30
  fill: '#ffffff',
31
  stroke: '#000000',
32
  strokeThickness: 2
33
});
34

35
// Create with gradient fill
36
const gradientStyle = new TextStyle({
37
  fill: ['#ffffff', '#ffff00', '#ff0000'],
38
  fillGradientType: TEXT_GRADIENT.LINEAR_VERTICAL,
39
  fontSize: 32
40
});
41
```
42

43
### Typography Properties
44

45
Core typography configuration including font family, size, style, and weight.
46

47
```typescript { .api }
48
/**
49
 * Font family name or array of fallback fonts
50
 */
51
fontFamily: string | string[];
52

53
/**
54
 * Font size as number (px) or string with units
55
 */
56
fontSize: number | string;
57

58
/**
59
 * Font style: normal, italic, or oblique
60
 */
61
fontStyle: TextStyleFontStyle;
62

63
/**
64
 * Font variant: normal or small-caps
65
 */
66
fontVariant: TextStyleFontVariant;
67

68
/**
69
 * Font weight: normal, bold, numeric values, etc.
70
 */
71
fontWeight: TextStyleFontWeight;
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
const style = new TextStyle();
78

79
// Set font family with fallbacks
80
style.fontFamily = ['Helvetica', 'Arial', 'sans-serif'];
81

82
// Set font size in different units
83
style.fontSize = 24;           // pixels
84
style.fontSize = '1.5em';      // em units
85
style.fontSize = '18pt';       // points
86

87
// Set font style and weight
88
style.fontStyle = 'italic';
89
style.fontWeight = 'bold';
90
style.fontVariant = 'small-caps';
91
```
92

93
### Fill Properties
94

95
Text fill configuration supporting solid colors, gradients, and patterns.
96

97
```typescript { .api }
98
/**
99
 * Fill style: color, gradient array, canvas gradient, or pattern
100
 */
101
fill: TextStyleFill;
102

103
/**
104
 * Gradient type when fill is an array
105
 */
106
fillGradientType: TEXT_GRADIENT;
107

108
/**
109
 * Custom gradient stop positions (0-1)
110
 */
111
fillGradientStops: number[];
112
```
113

114
**Usage Examples:**
115

116
```typescript
117
const style = new TextStyle();
118

119
// Solid color fills
120
style.fill = '#ff0000';        // hex string
121
style.fill = 0xff0000;         // hex number
122
style.fill = 'red';            // color name
123

124
// Gradient fills
125
style.fill = ['#ff0000', '#00ff00', '#0000ff'];
126
style.fillGradientType = TEXT_GRADIENT.LINEAR_HORIZONTAL;
127

128
// Custom gradient stops
129
style.fill = ['#ffffff', '#000000'];
130
style.fillGradientStops = [0.2, 0.8];
131
```
132

133
### Stroke Properties
134

135
Text outline configuration with color and thickness control.
136

137
```typescript { .api }
138
/**
139
 * Stroke color for text outline
140
 */
141
stroke: string | number;
142

143
/**
144
 * Thickness of the text outline
145
 * @default 0
146
 */
147
strokeThickness: number;
148
```
149

150
**Usage Examples:**
151

152
```typescript
153
const style = new TextStyle();
154

155
// Basic stroke
156
style.stroke = '#000000';
157
style.strokeThickness = 3;
158

159
// Colored stroke
160
style.stroke = 0x00ff00;
161
style.strokeThickness = 2;
162
```
163

164
### Drop Shadow Properties
165

166
Drop shadow effects with full control over appearance and positioning.
167

168
```typescript { .api }
169
/**
170
 * Enable drop shadow effect
171
 */
172
dropShadow: boolean;
173

174
/**
175
 * Drop shadow opacity (0-1)
176
 */
177
dropShadowAlpha: number;
178

179
/**
180
 * Drop shadow angle in radians
181
 */
182
dropShadowAngle: number;
183

184
/**
185
 * Drop shadow blur radius
186
 */
187
dropShadowBlur: number;
188

189
/**
190
 * Drop shadow color
191
 */
192
dropShadowColor: string | number;
193

194
/**
195
 * Drop shadow distance from text
196
 */
197
dropShadowDistance: number;
198
```
199

200
**Usage Examples:**
201

202
```typescript
203
const style = new TextStyle();
204

205
// Enable drop shadow
206
style.dropShadow = true;
207
style.dropShadowColor = '#000000';
208
style.dropShadowDistance = 5;
209
style.dropShadowAngle = Math.PI / 4;
210

211
// Soft shadow
212
style.dropShadowBlur = 4;
213
style.dropShadowAlpha = 0.5;
214
```
215

216
### Layout Properties
217

218
Text layout configuration including alignment, wrapping, and spacing.
219

220
```typescript { .api }
221
/**
222
 * Text alignment for multi-line text
223
 */
224
align: TextStyleAlign;
225

226
/**
227
 * Enable word wrapping
228
 */
229
wordWrap: boolean;
230

231
/**
232
 * Width threshold for word wrapping
233
 */
234
wordWrapWidth: number;
235

236
/**
237
 * Allow breaking words within characters
238
 */
239
breakWords: boolean;
240

241
/**
242
 * Whitespace handling behavior
243
 */
244
whiteSpace: TextStyleWhiteSpace;
245
```
246

247
**Usage Examples:**
248

249
```typescript
250
const style = new TextStyle();
251

252
// Text alignment
253
style.align = 'center';
254

255
// Word wrapping
256
style.wordWrap = true;
257
style.wordWrapWidth = 300;
258
style.breakWords = true;
259

260
// Whitespace handling
261
style.whiteSpace = 'pre-line';
262
```
263

264
### Spacing Properties
265

266
Character and line spacing configuration for typography fine-tuning.
267

268
```typescript { .api }
269
/**
270
 * Letter spacing amount
271
 * @default 0
272
 */
273
letterSpacing: number;
274

275
/**
276
 * Line height multiplier
277
 */
278
lineHeight: number;
279

280
/**
281
 * Additional space between lines
282
 * @default 0
283
 */
284
leading: number;
285
```
286

287
**Usage Examples:**
288

289
```typescript
290
const style = new TextStyle();
291

292
// Character spacing
293
style.letterSpacing = 2;
294

295
// Line spacing
296
style.lineHeight = 1.2;
297
style.leading = 4;
298
```
299

300
### Canvas Properties
301

302
Canvas-specific rendering properties for advanced text effects.
303

304
```typescript { .api }
305
/**
306
 * Line join style for stroke rendering
307
 */
308
lineJoin: TextStyleLineJoin;
309

310
/**
311
 * Miter limit for sharp corners
312
 */
313
miterLimit: number;
314

315
/**
316
 * Text baseline alignment
317
 */
318
textBaseline: TextStyleTextBaseline;
319

320
/**
321
 * Padding around text for effects
322
 */
323
padding: number;
324

325
/**
326
 * Trim transparent borders from texture
327
 */
328
trim: boolean;
329
```
330

331
**Usage Examples:**
332

333
```typescript
334
const style = new TextStyle();
335

336
// Canvas rendering properties
337
style.lineJoin = 'round';
338
style.miterLimit = 5;
339
style.textBaseline = 'middle';
340

341
// Texture optimization
342
style.padding = 4;
343
style.trim = true;
344
```
345

346
### Style Management Methods
347

348
Methods for cloning, resetting, and generating font strings from style configuration.
349

350
```typescript { .api }
351
/**
352
 * Creates a complete copy of the TextStyle
353
 * @returns New TextStyle instance with identical properties
354
 */
355
clone(): TextStyle;
356

357
/**
358
 * Resets all properties to default values
359
 */
360
reset(): void;
361

362
/**
363
 * Generates CSS font string for Canvas API
364
 * @returns Font string for use with canvas context
365
 */
366
toFontString(): string;
367
```
368

369
**Usage Examples:**
370

371
```typescript
372
const originalStyle = new TextStyle({
373
  fontSize: 24,
374
  fontFamily: 'Arial',
375
  fill: '#ffffff'
376
});
377

378
// Clone the style
379
const clonedStyle = originalStyle.clone();
380

381
// Reset to defaults
382
clonedStyle.reset();
383

384
// Generate font string
385
const fontString = originalStyle.toFontString();
386
console.log(fontString); // "normal normal normal 24px Arial"
387
```
388

389
### Change Tracking
390

391
Automatic change tracking system for efficient text updates.
392

393
```typescript { .api }
394
/**
395
 * Unique style ID that changes when properties are modified
396
 * Used internally for change detection
397
 */
398
styleID: number;
399
```
400

401
**Usage Examples:**
402

403
```typescript
404
const style = new TextStyle();
405
console.log(style.styleID); // e.g., 0
406

407
// Modify a property
408
style.fontSize = 32;
409
console.log(style.styleID); // e.g., 1
410

411
// Multiple changes increment the ID
412
style.fill = '#ff0000';
413
console.log(style.styleID); // e.g., 2
414
```
415

416
## Type Definitions
417

418
```typescript { .api }
419
// String union types for type safety
420
type TextStyleAlign = 'left' | 'center' | 'right' | 'justify';
421
type TextStyleFontStyle = 'normal' | 'italic' | 'oblique';
422
type TextStyleFontVariant = 'normal' | 'small-caps';
423
type TextStyleFontWeight = 'normal' | 'bold' | 'bolder' | 'lighter' | 
424
                          '100' | '200' | '300' | '400' | '500' | 
425
                          '600' | '700' | '800' | '900';
426
type TextStyleLineJoin = 'miter' | 'round' | 'bevel';
427
type TextStyleTextBaseline = 'alphabetic' | 'top' | 'hanging' | 
428
                            'middle' | 'ideographic' | 'bottom';
429
type TextStyleWhiteSpace = 'normal' | 'pre' | 'pre-line';
430

431
// Complex fill type supporting multiple formats
432
type TextStyleFill = string | string[] | number | number[] | 
433
                     CanvasGradient | CanvasPattern;
434

435
// Complete style interface
436
interface ITextStyle {
437
  align: TextStyleAlign;
438
  breakWords: boolean;
439
  dropShadow: boolean;
440
  dropShadowAlpha: number;
441
  dropShadowAngle: number;
442
  dropShadowBlur: number;
443
  dropShadowColor: string | number;
444
  dropShadowDistance: number;
445
  fill: TextStyleFill;
446
  fillGradientType: TEXT_GRADIENT;
447
  fillGradientStops: number[];
448
  fontFamily: string | string[];
449
  fontSize: number | string;
450
  fontStyle: TextStyleFontStyle;
451
  fontVariant: TextStyleFontVariant;
452
  fontWeight: TextStyleFontWeight;
453
  letterSpacing: number;
454
  lineHeight: number;
455
  lineJoin: TextStyleLineJoin;
456
  miterLimit: number;
457
  padding: number;
458
  stroke: string | number;
459
  strokeThickness: number;  
460
  textBaseline: TextStyleTextBaseline;
461
  trim: boolean;
462
  whiteSpace: TextStyleWhiteSpace;
463
  wordWrap: boolean;
464
  wordWrapWidth: number;
465
  leading: number;
466
}
467
```
468

469
## Advanced Styling Examples
470

471
**Multi-line Text with Custom Layout:**
472

473
```typescript
474
const multiLineStyle = new TextStyle({
475
  fontFamily: 'Georgia',
476
  fontSize: 18,
477
  fill: '#333333',
478
  align: 'justify',
479
  wordWrap: true,
480
  wordWrapWidth: 400,
481
  lineHeight: 1.4,
482
  leading: 2
483
});
484
```
485

486
**Glowing Text Effect:**
487

488
```typescript
489
const glowStyle = new TextStyle({
490
  fontSize: 32,
491
  fill: '#ffffff',
492
  stroke: '#00ffff',
493
  strokeThickness: 3,
494
  dropShadow: true,
495
  dropShadowColor: '#00ffff',
496
  dropShadowBlur: 8,
497
  dropShadowDistance: 0
498
});
499
```
500

501
**Gradient Text with Custom Stops:**
502

503
```typescript
504
const gradientStyle = new TextStyle({
505
  fontSize: 48,
506
  fill: ['#ff0000', '#ffff00', '#00ff00', '#00ffff', '#0000ff'],
507
  fillGradientType: TEXT_GRADIENT.LINEAR_HORIZONTAL,
508
  fillGradientStops: [0, 0.25, 0.5, 0.75, 1]
509
});
510
```