SilkText

import { SilkText } from 'pixi-silk/text';

Text from pixi-silk/text, drawn from signed distance fields. Glyphs come from any CSS font. They are baked once at one size into a shared SdfAtlas and drawn scaled, with the same per-pixel anti-aliasing as SilkGraphics. Every glyph is an instance of one mesh.

Outlines, shadows, glows and weight changes read the same distance field. Their reach is limited by the atlas field radius, about a quarter of the font size by default. Layout uses Canvas measureText, so line breaks and widths match PixiJS Text. Style changes relayout once, on the next render or the next read of SilkText.layout.

It has no rich text, per-character styles or right-to-left shaping. Glyphs combine code points one by one, so complex scripts and emoji sequences do not shape. Works with Pixi’s WebGL2 and WebGPU renderers.

Example#

const label = new SilkText({ text: 'Zoom me', fontSize: 14, fontWeight: 600, fill: 0xffffff });
label.anchor.set(0.5);
app.stage.addChild(label);

Extends#

• Mesh<SilkTextGeometry, Shader>

Constructors#

Constructor#

new SilkText(options?: string | SilkTextOptions): SilkText;

Parameters#

Returns#

SilkText

Overrides#

Mesh<SilkTextGeometry, Shader>.constructor

Properties#

Accessors#

aaWidth#

Get Signature#

get aaWidth(): number;

Width of the anti-aliasing ramp in device pixels. Larger is softer, 1 matches SilkGraphics.

Returns

number

Set Signature#

set aaWidth(v: number): void;

Sets SilkText.aaWidth.

Parameters

Returns

void

align#

Get Signature#

get align(): TextAlign;

Alignment of the lines.

Returns

TextAlign

Set Signature#

set align(v: TextAlign): void;

Sets SilkText.align.

Parameters

Returns

void

bounds#

Get Signature#

get bounds(): Bounds;

The local bounds of the mesh.

Returns

Bounds

Overrides#

Mesh.bounds

breakWords#

Get Signature#

get breakWords(): boolean;

Breaks words wider than SilkText.wordWrapWidth on their own. Needs wordWrap.

Returns

boolean

Set Signature#

set breakWords(v: boolean): void;

Sets SilkText.breakWords.

Parameters

Returns

void

dilate#

Get Signature#

get dilate(): number;

Grows (positive) or thins (negative) the glyphs, in local units.

Returns

number

Set Signature#

set dilate(v: number): void;

Sets SilkText.dilate.

Parameters

Returns

void

fill#

Get Signature#

get fill(): ColorSource | Gradient;

A colour, or a pixi-silk gradient spread over the text box.

Returns

ColorSource | Gradient

Set Signature#

set fill(v: ColorSource | Gradient): void;

Sets SilkText.fill.

Parameters

Returns

void

fontFamily#

Get Signature#

get fontFamily(): string;

CSS font family list. Glyphs of a new family are baked on first use.

Returns

string

Set Signature#

set fontFamily(v: string): void;

Sets SilkText.fontFamily.

Parameters

Returns

void

fontSize#

Get Signature#

get fontSize(): number;

Font size in local units. Glyphs are not rebaked, the atlas copy is scaled.

Returns

number

Set Signature#

set fontSize(v: number): void;

Sets SilkText.fontSize.

Parameters

Returns

void

fontStyle#

Get Signature#

get fontStyle(): "normal" | "italic" | "oblique";

normal, italic or oblique. A new style bakes new glyphs.

Returns

"normal" | "italic" | "oblique"

Set Signature#

set fontStyle(v: "normal" | "italic" | "oblique"): void;

Sets SilkText.fontStyle.

Parameters

Returns

void

fontWeight#

Get Signature#

get fontWeight(): string | number;

CSS font weight, as a number or a keyword. A new weight bakes new glyphs.

Returns

string | number

Set Signature#

set fontWeight(v: string | number): void;

Sets SilkText.fontWeight.

Parameters

Returns

void

glyphCount#

Get Signature#

get glyphCount(): number;

Glyph instances drawn: characters with ink. Spaces, shadows and outlines are not counted.

Returns

number

kerning#

Get Signature#

get kerning(): boolean;

Applies kerning pairs measured from Canvas measureText.

Returns

boolean

Set Signature#

set kerning(v: boolean): void;

Sets SilkText.kerning.

Parameters

Returns

void

layout#

Get Signature#

get layout(): TextLayout;

The whole layout: glyphs, lines and the caret stops of each line. Its units are local, but its origin is the top left of the text box. Add SilkText.layoutOffset to place it.

Returns

TextLayout

layoutOffset#

Get Signature#

get layoutOffset(): PointData;

Where the anchor puts the top left of the text box, in local units.

Returns

PointData

letterSpacing#

Get Signature#

get letterSpacing(): number;

Extra space after each character, in local units. May be negative.

Returns

number

Set Signature#

set letterSpacing(v: number): void;

Sets SilkText.letterSpacing.

Parameters

Returns

void

lineHeight#

Get Signature#

get lineHeight(): number;

Distance between baselines in local units. 0 uses the font’s ascent plus descent.

Returns

number

Set Signature#

set lineHeight(v: number): void;

Sets SilkText.lineHeight.

Parameters

Returns

void

lines#

Get Signature#

get lines(): readonly LayoutLine[];

The laid-out lines: text, width and baseline of each, in layout units (see SilkText.layout). Relayouts first if needed.

Returns

readonly LayoutLine[]

outline#

Get Signature#

get outline(): TextOutline | null;

A line around the glyphs, or null. Set a new object to change it, mutating this one does nothing.

Returns

TextOutline | null

Set Signature#

set outline(v: TextOutline | null): void;

Sets SilkText.outline.

Parameters

Returns

void

shadow#

Get Signature#

get shadow(): TextShadow | null;

A drop shadow or glow, or null. Set a new object to change it, mutating this one does nothing.

Returns

TextShadow | null

Set Signature#

set shadow(v: TextShadow | null): void;

Sets SilkText.shadow.

Parameters

Returns

void

style#

Get Signature#

get style(): Readonly<SilkTextStyle>;

The current style. Change it through the setters or SilkText.set.

Returns

Readonly<SilkTextStyle>

tabularNumbers#

Get Signature#

get tabularNumbers(): boolean;

Gives the digits one width, the widest digit’s advance, so readouts do not jitter.

Returns

boolean

Set Signature#

set tabularNumbers(v: boolean): void;

Sets SilkText.tabularNumbers.

Parameters

Returns

void

text#

Get Signature#

get text(): string;

The text. \n starts a new line. Numbers are converted with String().

Returns

string

Set Signature#

set text(value: string | number): void;

Sets SilkText.text.

Parameters

Returns

void

wordWrap#

Get Signature#

get wordWrap(): boolean;

Breaks lines at spaces to fit SilkText.wordWrapWidth.

Returns

boolean

Set Signature#

set wordWrap(v: boolean): void;

Sets SilkText.wordWrap.

Parameters

Returns

void

wordWrapWidth#

Get Signature#

get wordWrapWidth(): number;

Width that word wrap breaks lines at, in local units. Ignored while SilkText.wordWrap is false.

Returns

number

Set Signature#

set wordWrapWidth(v: number): void;

Sets SilkText.wordWrapWidth.

Parameters

Returns

void

Methods#

caretAt()#

caretAt(point: PointData, isStop?: (index: number) => boolean): CaretHit;

The caret position nearest to a local point, for clicks. isStop limits the offsets a caret may take, for example to grapheme cluster boundaries.

Parameters#

Returns#

CaretHit

caretRect()#

caretRect(index: number, upstream?: boolean): CaretRect;

Where a caret at index sits, in local units. upstream picks the end of a wrapped line.

Parameters#

Returns#

CaretRect

containsPoint()#

containsPoint(point: PointData): boolean;

Hit test against the text box (local coordinates).

Parameters#

Returns#

boolean

Overrides#

Mesh.containsPoint

destroy()#

destroy(options?: DestroyOptions): void;

Destroys this sprite renderable and optionally its texture.

Parameters#

Returns#

void

Example#

mesh.destroy();
mesh.destroy(true);
mesh.destroy({ texture: true, textureSource: true });

Overrides#

Mesh.destroy

rangeRects()#

rangeRects(from: number, to: number): TextRect[];

Highlight boxes of the text from from to to, one per line, in local units.

Parameters#

Returns#

TextRect[]

set()#

set(options: SilkTextStyle & {
  text?: string | number;
}): this;

Changes several style fields, and the text, at once. Fields left undefined keep their value. Relayouts once. Returns this.

Parameters#

Returns#

this

updateText()#

updateText(): void;

Lays the text out and bakes missing glyphs now. Happens on its own before the next frame and whenever you read the size, so you rarely need to call it.

Returns#

void