Phaser API Documentation

  Version: 
Filter
This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . GameObjects . TextStyle

This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . GameObjects . TextStyle

A TextStyle class manages all of the style settings for a Text object.

Text Game Objects create a TextStyle instance automatically, which is accessed via the Text.style property. You do not normally need to instantiate one yourself.

Constructor:

new TextStyle(text, style)

Parameters:

name type description
text Phaser.GameObjects.Text

The Text object that this TextStyle is styling.

style Phaser.Types.GameObjects.Text.TextStyle

The style settings to set.

Since: 3.0.0

Members

<private> _font: string
Focus
Focus

Description:

The font style, size and family.

Type:
string
Since: 3.0.0
Focus
Focus
align: string
Focus
Focus

Description:

The text alignment.

Type:
string
Default: 'left'
Since: 3.0.0
Focus
Focus
backgroundColor: string
Focus
Focus

Description:

The background color.

Type:
string
Since: 3.0.0
Focus
Focus
baselineX: number
Focus
Focus

Description:

The amount of horizontal padding added to the width of the text when calculating the font metrics.

Type:
number
Default: 1.2
Since: 3.3.0
Focus
Focus
baselineY: number
Focus
Focus

Description:

The amount of vertical padding added to the height of the text when calculating the font metrics.

Type:
number
Default: 1.4
Since: 3.3.0
Focus
Focus
color: string
Focus
Focus

Description:

The text fill color.

Type:
string
Default: '#fff'
Since: 3.0.0
Focus
Focus
fixedHeight: number
Focus
Focus

Description:

The fixed height of the text.

0 means no fixed height.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
fixedWidth: number
Focus
Focus

Description:

The fixed width of the text.

0 means no fixed with.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
fontFamily: string
Focus
Focus

Description:

The font family.

Type:
string
Default: 'Courier'
Since: 3.0.0
Focus
Focus
fontSize: string
Focus
Focus

Description:

The font size.

Type:
string
Default: '16px'
Since: 3.0.0
Focus
Focus
fontStyle: string
Focus
Focus

Description:

The font style.

Type:
string
Since: 3.0.0
Focus
Focus
maxLines: number
Focus
Focus

Description:

The maximum number of lines to draw.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus

Description:

The Text object that this TextStyle is styling.

Type:
Since: 3.0.0
Focus
Focus
resolution: number
Focus
Focus

Description:

The resolution the text is rendered to its internal canvas at. The default is 0, which means it will use the resolution set in the Game Config.

Type:
number
Default: 0
Since: 3.12.0
Focus
Focus
rtl: boolean
Focus
Focus

Description:

Whether the text should render right to left.

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
shadowBlur: number
Focus
Focus

Description:

The shadow blur radius.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
shadowColor: string
Focus
Focus

Description:

The shadow color.

Type:
string
Default: '#000'
Since: 3.0.0
Focus
Focus
shadowFill: boolean
Focus
Focus

Description:

Whether shadow fill is enabled or not.

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
shadowOffsetX: number
Focus
Focus

Description:

The horizontal shadow offset.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
shadowOffsetY: number
Focus
Focus

Description:

The vertical shadow offset.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
shadowStroke: boolean
Focus
Focus

Description:

Whether shadow stroke is enabled or not.

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
stroke: string
Focus
Focus

Description:

The text stroke color.

Type:
string
Default: '#fff'
Since: 3.0.0
Focus
Focus
strokeThickness: number
Focus
Focus

Description:

The text stroke thickness.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
testString: string
Focus
Focus

Description:

The test string to use when measuring the font.

Type:
string
Default: '|MÉqgy'
Since: 3.0.0
Focus
Focus
wordWrapCallback: TextStyleWordWrapCallback | null
Focus
Focus

Description:

A 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. Setting this directly will not re-run the word wrapping algorithm. To change the callback and re-wrap, use Phaser.GameObjects.TextStyle#setWordWrapCallback.

Type:
TextStyleWordWrapCallback | null
Default: null
Since: 3.24.0
Focus
Focus
wordWrapCallbackScope: object | null
Focus
Focus

Description:

The scope that will be applied when the wordWrapCallback is invoked. Setting this directly will not re-run the word wrapping algorithm. To change the callback and re-wrap, use Phaser.GameObjects.TextStyle#setWordWrapCallback.

Type:
object | null
Default: null
Since: 3.24.0
Focus
Focus
wordWrapUseAdvanced: boolean
Focus
Focus

Description:

Whether 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. Setting this property directly will not re-run the word wrapping algorithm. To change the advanced setting and re-wrap, use Phaser.GameObjects.TextStyle#setWordWrapWidth.

Type:
boolean
Default: false
Since: 3.24.0
Focus
Focus
wordWrapWidth: number | null
Focus
Focus

Description:

The maximum width of a line of text in pixels. Null means no line wrapping. Setting this property directly will not re-run the word wrapping algorithm. To change the width and re-wrap, use Phaser.GameObjects.TextStyle#setWordWrapWidth.

Type:
number | null
Default: null
Since: 3.24.0
Focus
Focus

Methods

destroy()
Focus
Focus

Description:

Destroy this Text Style.

Examples:
Since: 3.0.0
Focus
Focus
getTextMetrics()
Focus
Focus

Description:

Get the current text metrics.

Returns:
Description:

The text metrics.

Examples:
Since: 3.0.0
Focus
Focus
setAlign([align])
Focus
Focus

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:

name type arguments Default description
align string <optional> 'left'

The text alignment for multi-line text.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setBackgroundColor(color)
Focus
Focus

Description:

Set the background color.

Parameters:

name type description
color string

The background color.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setColor(color)
Focus
Focus

Description:

Set the text fill color.

Parameters:

name type description
color string

The text fill color.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setFill(color)
Focus
Focus

Description:

Set the text fill color.

Parameters:

name type description
color string

The text fill color.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setFixedSize(width, height)
Focus
Focus

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:

name type description
width number

The fixed width to set.

height number

The fixed height to set.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setFont(font, [updateText])
Focus
Focus

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.

Parameters:

name type arguments Default description
font string | object

The font family or font settings to set.

updateText boolean <optional> true

Whether to update the text immediately.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setFontFamily(family)
Focus
Focus

Description:

Set the font family.

Parameters:

name type description
family string

The font family.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setFontSize(size)
Focus
Focus

Description:

Set the font size.

Parameters:

name type description
size number | string

The font size.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setFontStyle(style)
Focus
Focus

Description:

Set the font style.

Parameters:

name type description
style string

The font style.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setMaxLines([max])
Focus
Focus

Description:

Set the maximum number of lines to draw.

Parameters:

name type arguments description
max number <optional>

The maximum number of lines to draw.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setResolution(value)
Focus
Focus

Description:

Set the resolution used by the Text object.

By default it will be set to match the resolution set in the Game Config, but you can override it via this method. It allows for much clearer text on High DPI devices, at the cost of memory because it uses larger internal Canvas textures for the Text.

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

Parameters:

name type description
value number

The resolution for this Text object to use.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.12.0
Focus
Focus
setShadow([x], [y], [color], [blur], [shadowStroke], [shadowFill])
Focus
Focus

Description:

Set the shadow settings.

Calling this method always re-measures the parent Text object, so only call it when you actually change the shadow settings.

Parameters:

name type arguments Default description
x number <optional> 0

The horizontal shadow offset.

y number <optional> 0

The vertical shadow offset.

color string <optional> '#000'

The shadow color.

blur number <optional> 0

The shadow blur radius.

shadowStroke boolean <optional> false

Whether to stroke the shadow.

shadowFill boolean <optional> true

Whether to fill the shadow.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setShadowBlur([blur])
Focus
Focus

Description:

Set the shadow blur radius.

Parameters:

name type arguments description
blur number <optional>

The shadow blur radius.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setShadowColor([color])
Focus
Focus

Description:

Set the shadow color.

Parameters:

name type arguments Default description
color string <optional> '#000'

The shadow color.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setShadowFill(enabled)
Focus
Focus

Description:

Enable or disable shadow fill.

Parameters:

name type description
enabled boolean

Whether shadow fill is enabled or not.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setShadowOffset([x], [y])
Focus
Focus

Description:

Set the shadow offset.

Parameters:

name type arguments description
x number <optional>

The horizontal shadow offset.

y number <optional>

The vertical shadow offset.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setShadowStroke(enabled)
Focus
Focus

Description:

Enable or disable shadow stroke.

Parameters:

name type description
enabled boolean

Whether shadow stroke is enabled or not.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setStroke(color, thickness)
Focus
Focus

Description:

Set the stroke settings.

Parameters:

name type description
color string

The stroke color.

thickness number

The stroke thickness.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setStyle(style, [updateText], [setDefaults])
Focus
Focus

Description:

Set the text style.

Parameters:

name type arguments Default description
style Phaser.Types.GameObjects.Text.TextStyle

The style settings to set.

updateText boolean <optional> true

Whether to update the text immediately.

setDefaults boolean <optional> false

Use the default values is not set, or the local values.

Returns:
Description:

The parent Text object.

Examples:
text.setStyle({
    fontSize: '64px',
    fontFamily: 'Arial',
    color: '#ffffff',
    align: 'center',
    backgroundColor: '#ff00ff'
});
Since: 3.0.0
Focus
Focus
setTestString(string)
Focus
Focus

Description:

Set the test string to use when measuring the font.

Parameters:

name type description
string string

The test string to use when measuring the font.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setWordWrapCallback(callback, [scope])
Focus
Focus

Description:

Set a custom callback for wrapping lines.

Pass in null to remove wrapping by callback.

Parameters:

name type arguments Default description
callback TextStyleWordWrapCallback

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

scope object <optional> null

The scope that will be applied when the callback is invoked.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
setWordWrapWidth(width, [useAdvancedWrap])
Focus
Focus

Description:

Set the width (in pixels) to use for wrapping lines.

Pass in null to remove wrapping by width.

Parameters:

name type arguments Default description
width number

The maximum width of a line in pixels. Set to null to remove wrapping.

useAdvancedWrap boolean <optional> false

Whether 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:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus
syncFont(canvas, context)
Focus
Focus

Description:

Synchronize the font settings to the given Canvas Rendering Context.

Parameters:

name type description
canvas HTMLCanvasElement

The Canvas Element.

context CanvasRenderingContext2D

The Canvas Rendering Context.

Examples:
Since: 3.0.0
Focus
Focus
syncShadow(context, enabled)
Focus
Focus

Description:

Synchronize the shadow settings to the given Canvas Rendering Context.

Parameters:

name type description
context CanvasRenderingContext2D

The Canvas Rendering Context.

enabled boolean

Whether shadows are enabled or not.

Examples:
Since: 3.0.0
Focus
Focus
syncStyle(canvas, context)
Focus
Focus

Description:

Synchronize the text style settings to the given Canvas Rendering Context.

Parameters:

name type description
canvas HTMLCanvasElement

The Canvas Element.

context CanvasRenderingContext2D

The Canvas Rendering Context.

Examples:
Since: 3.0.0
Focus
Focus
toJSON()
Focus
Focus

Description:

Build a JSON representation of this Text Style.

Returns:
Description:

A JSON representation of this Text Style.

Type:
  • object
Examples:
Since: 3.0.0
Focus
Focus
update(recalculateMetrics)
Focus
Focus

Description:

Update the style settings for the parent Text object.

Parameters:

name type description
recalculateMetrics boolean

Whether to recalculate font and text metrics.

Returns:
Description:

The parent Text object.

Examples:
Since: 3.0.0
Focus
Focus