tessl/npm-pixi--text

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Text Styling

Name: tessl/npm-pixi--text
Author: tessl

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.

Capabilities

TextStyle Constructor

Creates a new TextStyle object with optional initial style configuration.

/**
 * Creates a TextStyle with specified properties
 * @param style - Partial style configuration object
 */
constructor(style?: Partial<ITextStyle>);

Usage Examples:

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

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

// Create with custom properties
const customStyle = new TextStyle({
  fontFamily: 'Arial',
  fontSize: 24,
  fill: '#ffffff',
  stroke: '#000000',
  strokeThickness: 2
});

// Create with gradient fill
const gradientStyle = new TextStyle({
  fill: ['#ffffff', '#ffff00', '#ff0000'],
  fillGradientType: TEXT_GRADIENT.LINEAR_VERTICAL,
  fontSize: 32
});

Typography Properties

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

/**
 * Font family name or array of fallback fonts
 */
fontFamily: string | string[];

/**
 * Font size as number (px) or string with units
 */
fontSize: number | string;

/**
 * Font style: normal, italic, or oblique
 */
fontStyle: TextStyleFontStyle;

/**
 * Font variant: normal or small-caps
 */
fontVariant: TextStyleFontVariant;

/**
 * Font weight: normal, bold, numeric values, etc.
 */
fontWeight: TextStyleFontWeight;

Usage Examples:

const style = new TextStyle();

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

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

// Set font style and weight
style.fontStyle = 'italic';
style.fontWeight = 'bold';
style.fontVariant = 'small-caps';

Fill Properties

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

/**
 * Fill style: color, gradient array, canvas gradient, or pattern
 */
fill: TextStyleFill;

/**
 * Gradient type when fill is an array
 */
fillGradientType: TEXT_GRADIENT;

/**
 * Custom gradient stop positions (0-1)
 */
fillGradientStops: number[];

Usage Examples:

const style = new TextStyle();

// Solid color fills
style.fill = '#ff0000';        // hex string
style.fill = 0xff0000;         // hex number
style.fill = 'red';            // color name

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

// Custom gradient stops
style.fill = ['#ffffff', '#000000'];
style.fillGradientStops = [0.2, 0.8];

Stroke Properties

Text outline configuration with color and thickness control.

/**
 * Stroke color for text outline
 */
stroke: string | number;

/**
 * Thickness of the text outline
 * @default 0
 */
strokeThickness: number;

Usage Examples:

const style = new TextStyle();

// Basic stroke
style.stroke = '#000000';
style.strokeThickness = 3;

// Colored stroke
style.stroke = 0x00ff00;
style.strokeThickness = 2;

Drop Shadow Properties

Drop shadow effects with full control over appearance and positioning.

/**
 * Enable drop shadow effect
 */
dropShadow: boolean;

/**
 * Drop shadow opacity (0-1)
 */
dropShadowAlpha: number;

/**
 * Drop shadow angle in radians
 */
dropShadowAngle: number;

/**
 * Drop shadow blur radius
 */
dropShadowBlur: number;

/**
 * Drop shadow color
 */
dropShadowColor: string | number;

/**
 * Drop shadow distance from text
 */
dropShadowDistance: number;

Usage Examples:

const style = new TextStyle();

// Enable drop shadow
style.dropShadow = true;
style.dropShadowColor = '#000000';
style.dropShadowDistance = 5;
style.dropShadowAngle = Math.PI / 4;

// Soft shadow
style.dropShadowBlur = 4;
style.dropShadowAlpha = 0.5;

Layout Properties

Text layout configuration including alignment, wrapping, and spacing.

/**
 * Text alignment for multi-line text
 */
align: TextStyleAlign;

/**
 * Enable word wrapping
 */
wordWrap: boolean;

/**
 * Width threshold for word wrapping
 */
wordWrapWidth: number;

/**
 * Allow breaking words within characters
 */
breakWords: boolean;

/**
 * Whitespace handling behavior
 */
whiteSpace: TextStyleWhiteSpace;

Usage Examples:

const style = new TextStyle();

// Text alignment
style.align = 'center';

// Word wrapping
style.wordWrap = true;
style.wordWrapWidth = 300;
style.breakWords = true;

// Whitespace handling
style.whiteSpace = 'pre-line';

Spacing Properties

Character and line spacing configuration for typography fine-tuning.

/**
 * Letter spacing amount
 * @default 0
 */
letterSpacing: number;

/**
 * Line height multiplier
 */
lineHeight: number;

/**
 * Additional space between lines
 * @default 0
 */
leading: number;

Usage Examples:

const style = new TextStyle();

// Character spacing
style.letterSpacing = 2;

// Line spacing
style.lineHeight = 1.2;
style.leading = 4;

Canvas Properties

Canvas-specific rendering properties for advanced text effects.

/**
 * Line join style for stroke rendering
 */
lineJoin: TextStyleLineJoin;

/**
 * Miter limit for sharp corners
 */
miterLimit: number;

/**
 * Text baseline alignment
 */
textBaseline: TextStyleTextBaseline;

/**
 * Padding around text for effects
 */
padding: number;

/**
 * Trim transparent borders from texture
 */
trim: boolean;

Usage Examples:

const style = new TextStyle();

// Canvas rendering properties
style.lineJoin = 'round';
style.miterLimit = 5;
style.textBaseline = 'middle';

// Texture optimization
style.padding = 4;
style.trim = true;

Style Management Methods

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

/**
 * Creates a complete copy of the TextStyle
 * @returns New TextStyle instance with identical properties
 */
clone(): TextStyle;

/**
 * Resets all properties to default values
 */
reset(): void;

/**
 * Generates CSS font string for Canvas API
 * @returns Font string for use with canvas context
 */
toFontString(): string;

Usage Examples:

const originalStyle = new TextStyle({
  fontSize: 24,
  fontFamily: 'Arial',
  fill: '#ffffff'
});

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

// Reset to defaults
clonedStyle.reset();

// Generate font string
const fontString = originalStyle.toFontString();
console.log(fontString); // "normal normal normal 24px Arial"

Change Tracking

Automatic change tracking system for efficient text updates.

/**
 * Unique style ID that changes when properties are modified
 * Used internally for change detection
 */
styleID: number;

Usage Examples:

const style = new TextStyle();
console.log(style.styleID); // e.g., 0

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

// Multiple changes increment the ID
style.fill = '#ff0000';
console.log(style.styleID); // e.g., 2

Type Definitions

// String union types for type safety
type TextStyleAlign = 'left' | 'center' | 'right' | 'justify';
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';

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

// Complete style interface
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;
}

Advanced Styling Examples

Multi-line Text with Custom Layout:

const multiLineStyle = new TextStyle({
  fontFamily: 'Georgia',
  fontSize: 18,
  fill: '#333333',
  align: 'justify',
  wordWrap: true,
  wordWrapWidth: 400,
  lineHeight: 1.4,
  leading: 2
});

Glowing Text Effect:

const glowStyle = new TextStyle({
  fontSize: 32,
  fill: '#ffffff',
  stroke: '#00ffff',
  strokeThickness: 3,
  dropShadow: true,
  dropShadowColor: '#00ffff',
  dropShadowBlur: 8,
  dropShadowDistance: 0
});

Gradient Text with Custom Stops:

const gradientStyle = new TextStyle({
  fontSize: 48,
  fill: ['#ff0000', '#ffff00', '#00ff00', '#00ffff', '#0000ff'],
  fillGradientType: TEXT_GRADIENT.LINEAR_HORIZONTAL,
  fillGradientStops: [0, 0.25, 0.5, 0.75, 1]
});

Install with Tessl CLI