Skip to main content
Version: Phaser v4.0.0

Text

A Text Game Object.

Text objects work by creating their own internal hidden Canvas and then renders text to it using the standard Canvas fillText API. It then creates a texture from this canvas which is rendered to your game during the render pass.

Because it uses the Canvas API you can take advantage of all the features this offers, such as applying gradient fills to the text, or strokes, shadows and more. You can also use custom fonts loaded externally, such as Google or TypeKit Web fonts.

Important: The font name must be quoted if it contains certain combinations of digits or special characters, either when creating the Text object, or when setting the font via setFont or setFontFamily, e.g.:


this.add.text(0, 0, 'Hello World', { fontFamily: 'Georgia, "Goudy Bookletter 1911", Times, serif' });


this.add.text(0, 0, 'Hello World', { font: '"Press Start 2P"' });

You can only display fonts that are currently loaded and available to the browser: therefore fonts must be pre-loaded. Phaser does not do this for you, so you will require the use of a 3rd party font loader, or have the fonts readily available in the CSS on the page in which your Phaser game resides.

See this for the available default fonts across mobile browsers.

A note on performance: Every time the contents of a Text object changes, i.e. changing the text being displayed, or the style of the text, it needs to remake the Text canvas, and if on WebGL, re-upload the new texture to the GPU. This can be an expensive operation if used often, or with large quantities of Text objects in your game. If you run into performance issues you would be better off using Bitmap Text instead, as it benefits from batching and avoids expensive Canvas API calls.

Constructor

new Text(scene, x, y, text, style)

Parameters

nametypeoptionaldescription
scenePhaser.SceneNoThe Scene to which this Game Object belongs. A Game Object can only belong to one Scene at a time.
xnumberNoThe horizontal position of this Game Object in the world.
ynumberNoThe vertical position of this Game Object in the world.
textstring | Array.<string>NoThe text this Text object will display.
stylePhaser.Types.GameObjects.Text.TextStyleNoThe text style configuration object.

Scope: static

Extends

Phaser.GameObjects.GameObject
Phaser.GameObjects.Components.Alpha
Phaser.GameObjects.Components.BlendMode
Phaser.GameObjects.Components.ComputedSize
Phaser.GameObjects.Components.Crop
Phaser.GameObjects.Components.Depth
Phaser.GameObjects.Components.Flip
Phaser.GameObjects.Components.GetBounds
Phaser.GameObjects.Components.Mask
Phaser.GameObjects.Components.Origin
Phaser.GameObjects.Components.RenderNodes
Phaser.GameObjects.Components.ScrollFactor
Phaser.GameObjects.Components.Tint
Phaser.GameObjects.Components.Transform
Phaser.GameObjects.Components.Visible

Source: src/gameobjects/text/Text.js#L20
Since: 3.0.0

Inherited Members

From Phaser.GameObjects.Components.Alpha:

From Phaser.GameObjects.Components.BlendMode:

From Phaser.GameObjects.Components.ComputedSize:

From Phaser.GameObjects.Components.Crop:

From Phaser.GameObjects.Components.Depth:

From Phaser.GameObjects.Components.Filters:

From Phaser.GameObjects.Components.Flip:

From Phaser.GameObjects.Components.Mask:

From Phaser.GameObjects.Components.Origin:

From Phaser.GameObjects.Components.RenderNodes:

From Phaser.GameObjects.Components.ScrollFactor:

From Phaser.GameObjects.Components.Tint:

From Phaser.GameObjects.Components.Transform:

From Phaser.GameObjects.Components.Visible:

From Phaser.GameObjects.GameObject:


Public Members

autoRound

autoRound: boolean

Description:

Whether to automatically round line positions.

Source: src/gameobjects/text/Text.js#L160
Since: 3.0.0


canvas

canvas: HTMLCanvasElement

Description:

The canvas element that the text is rendered to.

Source: src/gameobjects/text/Text.js#L131
Since: 3.0.0


context

context: CanvasRenderingContext2D

Description:

The context of the canvas element that the text is rendered to.

Source: src/gameobjects/text/Text.js#L140
Since: 3.0.0


height

height: number

Description:

The height of this Text object.

Overrides: Phaser.GameObjects.Components.ComputedSize#height

Source: src/gameobjects/text/Text.js#L211
Since: 3.0.0


letterSpacing

letterSpacing: number

Description:

Adds / Removes spacing between characters. Can be a negative or positive number.

If you update this property directly, instead of using the setLetterSpacing method, then be sure to call updateText after, or you won't see the change reflected in the Text object.

Source: src/gameobjects/text/Text.js#L235
Since: 3.60.0


lineSpacing

lineSpacing: number

Description:

The line spacing value. This value is added to the font height to calculate the overall line height. Only has an effect if this Text object contains multiple lines of text.

If you update this property directly, instead of using the setLineSpacing method, then be sure to call updateText after, or you won't see the change reflected in the Text object.

Source: src/gameobjects/text/Text.js#L221
Since: 3.13.0


padding

padding: Phaser.Types.GameObjects.Text.TextPadding

Description:

Specify a padding value which is added to the line width and height when calculating the Text size. Allows you to add extra spacing if the browser is unable to accurately determine the true font dimensions.

Source: src/gameobjects/text/Text.js#L191
Since: 3.0.0


renderer

renderer: Phaser.Renderer.Canvas.CanvasRenderer, Phaser.Renderer.WebGL.WebGLRenderer

Description:

The renderer in use by this Text object.

Source: src/gameobjects/text/Text.js#L118
Since: 3.12.0


splitRegExp

splitRegExp: object

Description:

The Regular Expression that is used to split the text up into lines, in multi-line text. By default this is /(?:\r\n|\r|\n)/. You can change this RegExp to be anything else that you may need.

Source: src/gameobjects/text/Text.js#L170
Since: 3.0.0


style

style: Phaser.GameObjects.TextStyle

Description:

The Text Style object.

Manages the style of this Text object.

Source: src/gameobjects/text/Text.js#L149
Since: 3.0.0


text

text: string

Description:

The text string being rendered by this Text Game Object.

Source: src/gameobjects/text/Text.js#L1518
Since: 3.0.0


width

width: number

Description:

The width of this Text object.

Overrides: Phaser.GameObjects.Components.ComputedSize#width

Source: src/gameobjects/text/Text.js#L201
Since: 3.0.0


Inherited Methods

From Phaser.Events.EventEmitter:

From Phaser.GameObjects.Components.Alpha:

From Phaser.GameObjects.Components.BlendMode:

From Phaser.GameObjects.Components.ComputedSize:

From Phaser.GameObjects.Components.Crop:

From Phaser.GameObjects.Components.Depth:

From Phaser.GameObjects.Components.Filters:

From Phaser.GameObjects.Components.Flip:

From Phaser.GameObjects.Components.GetBounds:

From Phaser.GameObjects.Components.Mask:

From Phaser.GameObjects.Components.Origin:

From Phaser.GameObjects.Components.RenderNodes:

From Phaser.GameObjects.Components.RenderSteps:

From Phaser.GameObjects.Components.ScrollFactor:

From Phaser.GameObjects.Components.Tint:

From Phaser.GameObjects.Components.Transform:

From Phaser.GameObjects.Components.Visible:

From Phaser.GameObjects.GameObject:


Public Methods

advancedWordWrap

<instance> advancedWordWrap(text, context, wordWrapWidth)

Description:

Advanced wrapping algorithm that will wrap words as the line grows longer than its horizontal bounds. Consecutive spaces will be collapsed and replaced with a single space. Lines will be trimmed of white space before processing. Throws an error if wordWrapWidth is less than a single character.

Parameters:

nametypeoptionaldescription
textstringNoThe text to perform word wrap detection against.
contextCanvasRenderingContext2DNoThe Canvas Rendering Context.
wordWrapWidthnumberNoThe word wrap width.

Returns: string - The wrapped text.

Source: src/gameobjects/text/Text.js#L410
Since: 3.0.0


appendText

<instance> appendText(value, [addCR])

Description:

Appends the given text to the content already being displayed by this Text object.

An array of strings will be joined with \n line breaks.

Parameters:

nametypeoptionaldefaultdescription
valuestring | Array.<string>NoThe string, or array of strings, to be appended to the existing content of this Text object.
addCRbooleanYestrueInsert a carriage-return before the string value.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L661
Since: 3.60.0


basicWordWrap

<instance> basicWordWrap(text, context, wordWrapWidth)

Description:

Greedy wrapping algorithm that will wrap words as the line grows longer than its horizontal bounds. Spaces are not collapsed and whitespace is not trimmed.

Parameters:

nametypeoptionaldescription
textstringNoThe text to perform word wrap detection against.
contextCanvasRenderingContext2DNoThe Canvas Rendering Context.
wordWrapWidthnumberNoThe word wrap width.

Returns: string - The wrapped text.

Source: src/gameobjects/text/Text.js#L534
Since: 3.0.0


getTextMetrics

<instance> getTextMetrics()

Description:

Get the current text metrics.

Returns: Phaser.Types.GameObjects.Text.TextMetrics - The text metrics.

Source: src/gameobjects/text/Text.js#L1505
Since: 3.0.0


getWrappedText

<instance> getWrappedText([text])

Description:

Runs the given text through this Text objects word wrapping and returns the results as an array, where each element of the array corresponds to a wrapped line of text.

Parameters:

nametypeoptionaldescription
textstringYesThe text for which the wrapping will be calculated. If unspecified, the Text objects current text will be used.

Returns: Array.<string> - An array of strings with the pieces of wrapped text.

Source: src/gameobjects/text/Text.js#L605
Since: 3.0.0


initRTL

<instance> initRTL()

Description:

Initialize right to left text.

Source: src/gameobjects/text/Text.js#L331
Since: 3.0.0


preDestroy

<instance> preDestroy()

Description:

Internal destroy handler, called as part of the destroy process.

Access: protected

Source: src/gameobjects/text/Text.js#L1570
Since: 3.0.0


runWordWrap

<instance> runWordWrap(text)

Description:

Applies word wrapping to the given text and returns the result. If a custom word wrap callback has been set, it will be invoked. Otherwise, the advanced or basic word wrap algorithm will be used, depending on the style configuration. If no word wrap settings are active, the original text is returned unchanged.

Parameters:

nametypeoptionaldescription
textstringNoThe text to perform word wrap detection against.

Returns: string - The text after wrapping has been applied.

Source: src/gameobjects/text/Text.js#L365
Since: 3.0.0


setAlign

<instance> setAlign([align])

Description:

Set the alignment of the text in this Text object.

The argument can be one of: left, right, center or justify.

Alignment only works if the Text object has more than one line of text.

Parameters:

nametypeoptionaldefaultdescription
alignstringYes"'left'"The text alignment for multi-line text.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L1040
Since: 3.0.0


setBackgroundColor

<instance> setBackgroundColor(color)

Description:

Set the background color.

Parameters:

nametypeoptionaldescription
colorstringNoThe background color.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L841
Since: 3.0.0


setColor

<instance> setColor(color)

Description:

Set the text fill color.

Parameters:

nametypeoptionaldescription
colorstring | CanvasGradientCanvasPatternNo

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L876
Since: 3.0.0


setFill

<instance> setFill(color)

Description:

Set the fill style to be used by the Text object.

This can be any valid CanvasRenderingContext2D fillStyle value, such as a color (in hex, rgb, rgba, hsl or named values), a gradient or a pattern.

See the MDN fillStyle docs for more details.

Parameters:

nametypeoptionaldescription
colorstring | CanvasGradientCanvasPatternNo

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L856
Since: 3.0.0


setFixedSize

<instance> setFixedSize(width, height)

Description:

Set a fixed width and height for the text.

Pass in 0 for either of these parameters to disable fixed width or height respectively.

Parameters:

nametypeoptionaldescription
widthnumberNoThe fixed width to set. 0 disables fixed width.
heightnumberNoThe fixed height to set. 0 disables fixed height.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L823
Since: 3.0.0


setFont

<instance> setFont(font)

Description:

Set the font.

If a string is given, the font family is set.

If an object is given, the fontFamily, fontSize and fontStyle properties of that object are set.

Important: The font name must be quoted if it contains certain combinations of digits or special characters:


Text.setFont('"Press Start 2P"');

Equally, if you wish to provide a list of fallback fonts, then you should ensure they are all quoted properly, too:


Text.setFont('Georgia, "Goudy Bookletter 1911", Times, serif');

Parameters:

nametypeoptionaldescription
fontstringNoThe font family or font settings to set.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L726
Since: 3.0.0


setFontFamily

<instance> setFontFamily(family)

Description:

Set the font family.

Important: The font name must be quoted if it contains certain combinations of digits or special characters:


Text.setFontFamily('"Press Start 2P"');

Equally, if you wish to provide a list of fallback fonts, then you should ensure they are all quoted properly, too:


Text.setFontFamily('Georgia, "Goudy Bookletter 1911", Times, serif');

Parameters:

nametypeoptionaldescription
familystringNoThe font family.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L762
Since: 3.0.0


setFontSize

<instance> setFontSize(size)

Description:

Set the font size. Can be a string with a valid CSS unit, i.e. 16px, or a number.

Parameters:

nametypeoptionaldescription
sizestring | numberNoThe font size.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L793
Since: 3.0.0


setFontStyle

<instance> setFontStyle(style)

Description:

Set the font style.

Parameters:

nametypeoptionaldescription
stylestringNoThe font style.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L808
Since: 3.0.0


setLetterSpacing

<instance> setLetterSpacing(value)

Description:

Sets the letter spacing value.

This will add, or remove spacing between each character of this Text Game Object. The value can be either positive or negative. Positive values increase the space between each character, whilst negative values decrease it. Note that some fonts are spaced naturally closer together than others.

Please understand that enabling this feature will cause Phaser to render each character in this Text object one by one, rather than use a draw for the whole string. This makes it extremely expensive when used with either long strings, or lots of strings in total. You will be better off creating bitmap font text if you need to display large quantities of characters with fine control over the letter spacing.

Parameters:

nametypeoptionaldescription
valuenumberNoThe amount to add to the letter width. Set to zero to disable.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L1099
Since: 3.70.0


setLineSpacing

<instance> setLineSpacing(value)

Description:

Sets the line spacing value.

This value is added to the height of the font when calculating the overall line height. This only has an effect if this Text object consists of multiple lines of text.

Parameters:

nametypeoptionaldescription
valuenumberNoThe amount to add to the font height to achieve the overall line height.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L1079
Since: 3.13.0


setMaxLines

<instance> setMaxLines([max])

Description:

Set the maximum number of lines to draw.

Parameters:

nametypeoptionaldefaultdescription
maxnumberYes0The maximum number of lines to draw.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L1192
Since: 3.0.0


setPadding

<instance> setPadding(left, [top], [right], [bottom])

Description:

Sets the padding applied around the text content when calculating the canvas size.

The first argument can be either a number or a padding configuration object. When a number is given, it is applied to all four sides unless the other arguments override them. When an object is given, you can specify left, right, top, and bottom individually, or use x to set both left and right simultaneously, and y to set both top and bottom.

Parameters:

nametypeoptionaldescription
leftnumber | Phaser.Types.GameObjects.Text.TextPaddingNoThe left padding value, or a padding config object.
topnumberYesThe top padding value.
rightnumberYesThe right padding value.
bottomnumberYesThe bottom padding value.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L1125
Since: 3.0.0


setResolution

<instance> setResolution(value)

Description:

Set the resolution of the Texture used by this Text object.

Setting resolution above 1 is useful only if you're scaling up this Text object (or an ancestor) or zooming a Camera on it. Otherwise, any extra detail in the Texture would just be lost during rendering.

Please use with caution, as the more high-resolution Text you have, the more memory it uses.

Parameters:

nametypeoptionaldescription
valuenumberNoThe resolution for this Text object to use, relative to 1.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L1059
Since: 3.12.0


setRTL

<instance> setRTL([rtl])

Description:

Render text from right-to-left or left-to-right.

Parameters:

nametypeoptionaldefaultdescription
rtlbooleanYestrueSet to true to render from right-to-left.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L1207
Since: 3.70.0


setShadow

<instance> setShadow([x], [y], [color], [blur], [shadowStroke], [shadowFill])

Description:

Set the shadow settings.

Parameters:

nametypeoptionaldefaultdescription
xnumberYes0The horizontal shadow offset.
ynumberYes0The vertical shadow offset.
colorstringYes"'#000'"The shadow color.
blurnumberYes0The shadow blur radius.
shadowStrokebooleanYesfalseWhether to stroke the shadow.
shadowFillbooleanYestrueWhether to fill the shadow.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L907
Since: 3.0.0


setShadowBlur

<instance> setShadowBlur(blur)

Description:

Set the shadow blur radius.

Parameters:

nametypeoptionaldescription
blurnumberNoThe shadow blur radius.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L958
Since: 3.0.0


setShadowColor

<instance> setShadowColor(color)

Description:

Set the shadow color.

Parameters:

nametypeoptionaldescription
colorstringNoThe shadow color.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L943
Since: 3.0.0


setShadowFill

<instance> setShadowFill(enabled)

Description:

Enable or disable shadow fill.

Parameters:

nametypeoptionaldescription
enabledbooleanNoWhether shadow fill is enabled or not.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L988
Since: 3.0.0


setShadowOffset

<instance> setShadowOffset(x, y)

Description:

Set the shadow offset.

Parameters:

nametypeoptionaldescription
xnumberNoThe horizontal shadow offset.
ynumberNoThe vertical shadow offset.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L927
Since: 3.0.0


setShadowStroke

<instance> setShadowStroke(enabled)

Description:

Enable or disable shadow stroke.

Parameters:

nametypeoptionaldescription
enabledbooleanNoWhether shadow stroke is enabled or not.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L973
Since: 3.0.0


setStroke

<instance> setStroke(color, thickness)

Description:

Set the stroke settings.

Parameters:

nametypeoptionaldescription
colorstring | CanvasGradientCanvasPatternNo
thicknessnumberNoThe stroke thickness.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L891
Since: 3.0.0


setStyle

<instance> setStyle(style)

Description:

Set the text style.

Parameters:

nametypeoptionaldescription
styleobjectNoThe style settings to set.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L702
Since: 3.0.0


setText

<instance> setText(value)

Description:

Set the text to display.

An array of strings will be joined with \n line breaks.

Parameters:

nametypeoptionaldescription
valuestring | Array.<string>NoThe string, or array of strings, to be set as the content of this Text object.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L627
Since: 3.0.0


setWordWrapCallback

<instance> setWordWrapCallback(callback, [scope])

Description:

Set a custom callback for wrapping lines. Pass in null to remove wrapping by callback.

Parameters:

nametypeoptionaldefaultdescription
callbackTextStyleWordWrapCallbackNoA custom function that will be responsible for wrapping the text. It will receive two arguments: text (the string to wrap), textObject (this Text instance). It should return the wrapped lines either as an array of lines or as a string with newline characters in place to indicate where breaks should happen.
scopeobjectYesnullThe scope that will be applied when the callback is invoked.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L1021
Since: 3.0.0


setWordWrapWidth

<instance> setWordWrapWidth(width, [useAdvancedWrap])

Description:

Set the width (in pixels) to use for wrapping lines. Pass in null to remove wrapping by width.

Parameters:

nametypeoptionaldefaultdescription
widthnumber | nullNoThe maximum width of a line in pixels. Set to null to remove wrapping.
useAdvancedWrapbooleanYesfalseWhether or not to use the advanced wrapping algorithm. If true, spaces are collapsed and whitespace is trimmed from lines. If false, spaces and whitespace are left as is.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L1003
Since: 3.0.0


toJSON

<instance> toJSON()

Description:

Build a JSON representation of the Text object.

Overrides: Phaser.GameObjects.GameObject#toJSON

Returns: Phaser.Types.GameObjects.JSONGameObject - A JSON representation of the Text object.

Source: src/gameobjects/text/Text.js#L1539
Since: 3.0.0


updateText

<instance> updateText()

Description:

Recalculates and re-renders the text content onto the internal canvas. This is called automatically whenever the text string or any style property changes. It handles word wrapping, text sizing, multi-line layout, alignment, shadows, stroke, and letter spacing. If the renderer is WebGL, the updated canvas is re-uploaded to the GPU as a new texture. You should call this manually only if you have updated lineSpacing or letterSpacing directly without using their corresponding setter methods.

Returns: Phaser.GameObjects.Text - This Text object.

Source: src/gameobjects/text/Text.js#L1256
Since: 3.0.0