Class: TextStyle

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.

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
Source: src/gameobjects/text/TextStyle.js (Line 43)

Members

align :string

The text alignment.

Type:
  • string
Since: 3.0.0
Default Value:
  • 'left'
Source: src/gameobjects/text/TextStyle.js (Line 202)

backgroundColor :string

The background color.

Type:
  • string
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 103)

baselineX :number

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

Type:
  • number
Since: 3.3.0
Default Value:
  • 1.2
Source: src/gameobjects/text/TextStyle.js (Line 277)

baselineY :number

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

Type:
  • number
Since: 3.3.0
Default Value:
  • 1.4
Source: src/gameobjects/text/TextStyle.js (Line 287)

color :string

The text fill color.

Type:
  • string
Since: 3.0.0
Default Value:
  • '#fff'
Source: src/gameobjects/text/TextStyle.js (Line 112)

fixedHeight :number

The fixed height of the text.

0 means no fixed height.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/text/TextStyle.js (Line 234)

fixedWidth :number

The fixed width of the text.

0 means no fixed with.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/text/TextStyle.js (Line 222)

fontFamily :string

The font family.

Type:
  • string
Since: 3.0.0
Default Value:
  • 'Courier'
Source: src/gameobjects/text/TextStyle.js (Line 74)

fontSize :string

The font size.

Type:
  • string
Since: 3.0.0
Default Value:
  • '16px'
Source: src/gameobjects/text/TextStyle.js (Line 84)

fontStyle :string

The font style.

Type:
  • string
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 94)

maxLines :number

The maximum number of lines to draw.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/text/TextStyle.js (Line 212)

parent :Phaser.GameObjects.Text

The Text object that this TextStyle is styling.

Type:
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 65)

resolution :number

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
Since: 3.12.0
Default Value:
  • 0
Source: src/gameobjects/text/TextStyle.js (Line 246)

rtl :boolean

Whether the text should render right to left.

Type:
  • boolean
Since: 3.0.0
Default Value:
  • false
Source: src/gameobjects/text/TextStyle.js (Line 257)

shadowBlur :number

The shadow blur radius.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/text/TextStyle.js (Line 172)

shadowColor :string

The shadow color.

Type:
  • string
Since: 3.0.0
Default Value:
  • '#000'
Source: src/gameobjects/text/TextStyle.js (Line 162)

shadowFill :boolean

Whether shadow fill is enabled or not.

Type:
  • boolean
Since: 3.0.0
Default Value:
  • false
Source: src/gameobjects/text/TextStyle.js (Line 192)

shadowOffsetX :number

The horizontal shadow offset.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/text/TextStyle.js (Line 142)

shadowOffsetY :number

The vertical shadow offset.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/text/TextStyle.js (Line 152)

shadowStroke :boolean

Whether shadow stroke is enabled or not.

Type:
  • boolean
Since: 3.0.0
Default Value:
  • false
Source: src/gameobjects/text/TextStyle.js (Line 182)

stroke :string

The text stroke color.

Type:
  • string
Since: 3.0.0
Default Value:
  • '#fff'
Source: src/gameobjects/text/TextStyle.js (Line 122)

strokeThickness :number

The text stroke thickness.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/text/TextStyle.js (Line 132)

testString :string

The test string to use when measuring the font.

Type:
  • string
Since: 3.0.0
Default Value:
  • '|MÉqgy'
Source: src/gameobjects/text/TextStyle.js (Line 267)

wordWrapCallback :TextStyleWordWrapCallback|null

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:
Since: 3.24.0
Default Value:
  • null
Source: src/gameobjects/text/TextStyle.js (Line 309)

wordWrapCallbackScope :object|null

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
Since: 3.24.0
Default Value:
  • null
Source: src/gameobjects/text/TextStyle.js (Line 324)

wordWrapUseAdvanced :boolean

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
Since: 3.24.0
Default Value:
  • false
Source: src/gameobjects/text/TextStyle.js (Line 336)

wordWrapWidth :number|null

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
Since: 3.24.0
Default Value:
  • null
Source: src/gameobjects/text/TextStyle.js (Line 297)

Methods

destroy()

Destroy this Text Style.

Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 1087)

getTextMetrics()

Get the current text metrics.

Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 1046)
Returns:

The text metrics.

Type
Phaser.Types.GameObjects.Text.TextMetrics

setAlign( [align])

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 Argument Default Description
align string <optional>
 'left'

The text alignment for multi-line text.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 1004)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setBackgroundColor(color)

Set the background color.

Parameters:
Name Type Description
color string

The background color.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 715)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setColor(color)

Set the text fill color.

Parameters:
Name Type Description
color string

The text fill color.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 749)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setFill(color)

Set the text fill color.

Parameters:
Name Type Description
color string

The text fill color.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 732)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setFixedSize(width, height)

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.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 684)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setFont(font [, updateText])

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 Argument Default Description
font string | object

The font family or font settings to set.
updateText boolean <optional>
 true

Whether to update the text immediately.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 540)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setFontFamily(family)

Set the font family.

Parameters:
Name Type Description
family string

The font family.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 596)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setFontSize(size)

Set the font size.

Parameters:
Name Type Description
size number | string

The font size.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 640)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setFontStyle(style)

Set the font style.

Parameters:
Name Type Description
style string

The font style.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 618)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setMaxLines( [max])

Set the maximum number of lines to draw.

Parameters:
Name Type Argument Default Description
max number <optional>
 0

The maximum number of lines to draw.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 1027)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setResolution(value)

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.
Since: 3.12.0
Source: src/gameobjects/text/TextStyle.js (Line 766)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

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

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 Argument 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.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 822)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setShadowBlur( [blur])

Set the shadow blur radius.

Parameters:
Name Type Argument Default Description
blur number <optional>
 0

The shadow blur radius.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 900)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setShadowColor( [color])

Set the shadow color.

Parameters:
Name Type Argument Default Description
color string <optional>
 '#000'

The shadow color.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 881)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setShadowFill(enabled)

Enable or disable shadow fill.

Parameters:
Name Type Description
enabled boolean

Whether shadow fill is enabled or not.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 936)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setShadowOffset( [x] [, y])

Set the shadow offset.

Parameters:
Name Type Argument Default Description
x number <optional>
 0

The horizontal shadow offset.
y number <optional>
 0

The vertical shadow offset.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 859)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setShadowStroke(enabled)

Enable or disable shadow stroke.

Parameters:
Name Type Description
enabled boolean

Whether shadow stroke is enabled or not.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 919)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setStroke(color, thickness)

Set the stroke settings.

Parameters:
Name Type Description
color string

The stroke color.
thickness number

The stroke thickness.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 789)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setStyle(style [, updateText] [, setDefaults])

Set the text style.

Parameters:
Name Type Argument 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.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 380)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text
Example
text.setStyle({
    fontSize: '64px',
    fontFamily: 'Arial',
    color: '#ffffff',
    align: 'center',
    backgroundColor: '#ff00ff'
});

setTestString(string)

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.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 667)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setWordWrapCallback(callback [, scope])

Set a custom callback for wrapping lines.

Pass in null to remove wrapping by callback.

Parameters:
Name Type Argument 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.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 978)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

setWordWrapWidth(width [, useAdvancedWrap])

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

Pass in null to remove wrapping by width.

Parameters:
Name Type Argument 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.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 953)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text

syncFont(canvas, context)

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.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 456)

syncShadow(context, enabled)

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.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 491)

syncStyle(canvas, context)

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.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 470)

toJSON()

Build a JSON representation of this Text Style.

Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 1065)
Returns:

A JSON representation of this Text Style.

Type
object

update(recalculateMetrics)

Update the style settings for the parent Text object.

Parameters:
Name Type Description
recalculateMetrics boolean

Whether to recalculate font and text metrics.
Since: 3.0.0
Source: src/gameobjects/text/TextStyle.js (Line 518)
Returns:

The parent Text object.

Type
Phaser.GameObjects.Text