or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdtext-measurement.mdtext-rendering.mdtext-styling.md
tile.json

tessl/npm-pixi--text

Text rendering capabilities for PixiJS using Canvas API with comprehensive typography controls and WebGL integration

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@pixi/text@6.5.x

To install, run

npx @tessl/cli install tessl/npm-pixi--text@6.5.0

index.mddocs/

@pixi/text

@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.

Package Information

  • Package Name: @pixi/text
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @pixi/text

Core Imports

import { Text, TextStyle, TextMetrics, TEXT_GRADIENT } from "@pixi/text";

For CommonJS:

const { Text, TextStyle, TextMetrics, TEXT_GRADIENT } = require("@pixi/text");

Basic Usage

import { Text, TextStyle } from "@pixi/text";

// Create a styled text object
const style = new TextStyle({
  fontFamily: 'Arial',
  fontSize: 36,
  fill: '#ffffff',
  stroke: '#000000',
  strokeThickness: 4,
  dropShadow: true,
  dropShadowColor: '#000000',
  dropShadowBlur: 4,
  dropShadowAngle: Math.PI / 6,
  dropShadowDistance: 6,
  wordWrap: true,
  wordWrapWidth: 440
});

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

// Update text content
text.text = 'Updated text content';

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

Architecture

@pixi/text is built around three core components:

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

Capabilities

Text Rendering

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

class Text extends Sprite {
  constructor(text?: string | number, style?: Partial<ITextStyle> | TextStyle, canvas?: HTMLCanvasElement);
  
  // Static properties
  static nextLineHeightBehavior: boolean;
  static experimentalLetterSpacing: boolean;
  
  // Instance properties
  text: string;
  style: TextStyle | Partial<ITextStyle>;
  resolution: number;
  width: number;
  height: number;
  canvas: HTMLCanvasElement;
  context: CanvasRenderingContext2D;
  localStyleID: number;
  dirty: boolean;
  
  // Methods
  updateText(respectDirty: boolean): void;
  updateTransform(): void;
  getBounds(skipUpdate?: boolean, rect?: Rectangle): Rectangle;
  getLocalBounds(rect?: Rectangle): Rectangle;
  destroy(options?: IDestroyOptions | boolean): void;
}

Text Rendering

Text Styling

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

class TextStyle implements ITextStyle {
  constructor(style?: Partial<ITextStyle>);
  
  // Typography
  fontFamily: string | string[];
  fontSize: number | string;
  fontStyle: TextStyleFontStyle;
  fontWeight: TextStyleFontWeight;
  
  // Colors and Effects
  fill: TextStyleFill;
  stroke: string | number;
  strokeThickness: number;
  dropShadow: boolean;
  
  // Layout
  align: TextStyleAlign;
  wordWrap: boolean;
  wordWrapWidth: number;
  
  clone(): TextStyle;
  reset(): void;
  toFontString(): string;
}

Text Styling

Text Measurement

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

class TextMetrics {
  constructor(text: string, style: TextStyle, width: number, height: number, 
              lines: string[], lineWidths: number[], lineHeight: number, 
              maxLineWidth: number, fontProperties: IFontMetrics);
  
  // Static methods
  static measureText(text: string, style: TextStyle, wordWrap?: boolean, 
                     canvas?: HTMLCanvasElement | OffscreenCanvas): TextMetrics;
  static measureFont(font: string): IFontMetrics;
  static clearMetrics(font?: string): void;
  static isBreakingSpace(char: string, nextChar?: string): boolean;
  static canBreakWords(token: string, breakWords: boolean): boolean;
  static canBreakChars(char: string, nextChar: string, token: string, index: number, breakWords: boolean): boolean;
  static wordWrapSplit(token: string): string[];
  
  // Static properties
  static METRICS_STRING: string;
  static BASELINE_SYMBOL: string;
  static BASELINE_MULTIPLIER: number;
  static HEIGHT_MULTIPLIER: number;
  static get _canvas(): HTMLCanvasElement | OffscreenCanvas;
  static get _context(): CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
  
  // Instance properties
  text: string;
  style: TextStyle;
  width: number;
  height: number;
  lines: string[];
  lineWidths: number[];
  lineHeight: number;
  maxLineWidth: number;
  fontProperties: IFontMetrics;
}

Text Measurement

Types

// Core interfaces
interface ITextStyle {
  align: TextStyleAlign;
  breakWords: boolean;
  dropShadow: boolean;
  dropShadowAlpha: number;
  dropShadowAngle: number;
  dropShadowBlur: number;
  dropShadowColor: string | number;
  dropShadowDistance: number;
  fill: TextStyleFill;
  fillGradientType: TEXT_GRADIENT;
  fillGradientStops: number[];
  fontFamily: string | string[];
  fontSize: number | string;
  fontStyle: TextStyleFontStyle;
  fontVariant: TextStyleFontVariant;
  fontWeight: TextStyleFontWeight;
  letterSpacing: number;
  lineHeight: number;
  lineJoin: TextStyleLineJoin;
  miterLimit: number;
  padding: number;
  stroke: string | number;
  strokeThickness: number;
  textBaseline: TextStyleTextBaseline;
  trim: boolean;
  whiteSpace: TextStyleWhiteSpace;
  wordWrap: boolean;
  wordWrapWidth: number;
  leading: number;
}

interface IFontMetrics {
  ascent: number;
  descent: number;
  fontSize: number;
}

interface IDestroyOptions {
  children?: boolean;
  texture?: boolean;
  baseTexture?: boolean;
}

// Rectangle from @pixi/math
interface Rectangle {
  x: number;
  y: number;
  width: number;
  height: number;
}

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

// Constants
enum TEXT_GRADIENT {
  LINEAR_VERTICAL = 0,
  LINEAR_HORIZONTAL = 1
}