Rich text markup

Use markup in Label components and GUI text nodes to apply nested visual styles and effects, and inspect links and sprites from Lua.

label.set_text("#label", "Score: <color=#69D2E7>1200</color>")

Alternatively, define a reusable named object style on the font and select it from a link:

local fontpath = "/fonts/ui.fontc"
font.set_style(fontpath, "menu_link", "<color=#69D2E7>")
label.set_text("#label", "Open <link style=menu_link src=inventory>inventory</link>")

Tag reference

Tag	Purpose	Example
color	Set the glyph face color.
size	Change glyph shaping and layout size.
gradient	Apply a static or animated color gradient.
ul	Underline text.
strike	Strike through text.
outline	Set the glyph outline width and color.
shadow	Add a shadow to text.
shake	Apply an animated random offset.
wave	Move text in an animated sine wave.
sprite	Add an inline sprite object.
link	Add an interactive link object.

Syntax

Tags and attribute names are case-sensitive. A paired tag applies to the visible UTF-32 text inside it. Sprite objects use self-closing tags.

<color=#69D2E7>colored text</color>
<ul pattern=dashed>underlined text</ul>
<outline size=2 color=#000000>outlined text</outline>
<shadow x=2 y=-2 color=#00000080>shadowed text</shadow>
<sprite src=images/icon.png width=2em/>

Attributes

Attributes may be unquoted when they contain no whitespace, or quoted with single or double quotes. color and size support a shorthand first value as well as the named value form.

<color=#FF8800>Orange</color>
<color value="#FF8800">Orange</color>
<size='120%'>Larger</size>

Nesting

Tags must close in last-in, first-out order. Inner style values override the same property from an outer style. Different properties combine. Span effects remain independently active, so nested gradients multiply colors and nested position effects add their offsets.

<color=#FFCC00>
    Gold <outline size=2 color=#000000>with a black outline</outline>
</color>

Entities

Use &, ', >, <, and " for reserved characters in visible text. Numeric entities are not currently supported.

Tags

Rich-text tags either style an enclosed text span or describe an object that can be inspected from Lua. Style tags use a matching closing tag. The sprite object is self-closing, while link encloses its linked text.

color

Sets the glyph face color. Colors use #RRGGBB or #RRGGBBAA. The hash prefix is required; 0xFF0000 and FF0000 are invalid. The result multiplies the label or renderer base color.

<color=#00FF00>Opaque green</color>
<color=#00FF0080>Half-alpha green</color>

size

Changes glyph shaping and layout size, not only vertex scale. Relative values always use the layout’s base font size. They do not compound with an enclosing size tag.

<size=24px>Exactly 24 pixels</size>
<size=120%>120% of the layout base size</size>
<size=2em>Twice the layout base size</size>

gradient

A gradient accepts exactly one complete attribute set. Mixing sets or omitting a member is invalid.

When fit is omitted, fit=span distributes the gradient across the complete tagged text. fit=glyph samples each shaped text position independently. Optional hz specifies complete flowing animation cycles per second; its default of zero keeps the gradient static. The repeating mirrored color ramp flows continuously and wraps without a color jump. direction=forward is the default; use direction=reverse to reverse the flow.

<gradient left=#FF00FF right=#FFFFFF>Horizontal Gradient</gradient>

<gradient hz=0.25 fit=glyph bottom=#182848 top=#4B6CB7>Animated vertical glyphs</gradient>

<gradient hz=0.25 direction=reverse left=#FF0000 right=#0000FF>Reverse flow</gradient>

<gradient hz=0.25 direction=reverse fit=span left=#FF0000 right=#0000FF>One animated span color</gradient>

<gradient fit=glyph tl=#FF0000 tr=#00FF00 bl=#0000FF br=#FFFFFF>
    Four corners
</gradient>

Four corner

Animated

Gradient colors multiply the current face color. A gradient inside color=#808080 therefore cannot produce a channel brighter than that base multiplier.

ul

Draws an underline using the font’s underline metrics when they are available. The tag has no independent color: the line inherits the effective face color, including horizontal, vertical, and four-corner gradients.

<ul>Solid underline</ul>
<ul pattern=dashed>Dashed underline</ul>
<ul><gradient left=#FF00FF right=#FFFFFF>Gradient line</gradient></ul>

strike

Draws a line through the enclosed text. It accepts the same pattern values as ul and likewise inherits the effective face color.

<strike>No longer available</strike>
<strike pattern=dashed>Dashed strikethrough</strike>

outline

Sets outline width, outline color, or both. At least one attribute is required. A zero width explicitly disables the outline for the span.

<outline size=3 color=#000000>Black outline</outline>
<outline color=#FF0000>Keep inherited width, change color</outline>
<outline size=0>Disable inherited outline</outline>

shadow

Adds a hard shadow to the enclosed text. At least one attribute is required. Attributes omitted by a nested tag retain the enclosing shadow value; attributes omitted by the outermost tag retain the font’s base shadow value.

<shadow x=6 y=-6 blur=4 color=#000000A0>Shadow</shadow>
<shadow x=-2>Override only the horizontal offset</shadow>

shake

Applies a deterministic animated random offset without changing line breaking or layout bounds. The effect keeps time internally; scripts do not need to modify the label text for each animation frame.

<shake>Default shake</shake>
<shake hz=12 amplitude=0.8 fit=glyph>Glyph shake</shake>
<shake hz=12 amplitude=0.8 fit=span>Rigid span shake</shake>

wave

Moves characters up and down in an animated sine wave without changing line breaking or layout bounds. The layout accumulates animation time when it is updated.

<wave>Animated character wave</wave>
<wave amplitude=4 hz=3 wavelength=8 fit=glyph>Travelling wave</wave>
<wave amplitude=4 hz=3 wavelength=8 fit=glyph direction=reverse>Reverse travelling wave</wave>
<wave amplitude=4 hz=1 fit=span>Whole span moves together</wave>

sprite

Adds a self-closing sprite object at the current position in the visible text. Its attributes are preserved as metadata for label.get_layout_objects() and gui.get_layout_objects().

A <sprite src=engine/engine/content/builtins/assets/images/logo/logo_256.png/> logo
<sprite src=images/banner.png width=4em height=2em/>
<sprite src=images/icons.atlas animation=coin width=2em/>

Dimensions accept positive bare layout units, px, em, or %. Both em and % use the text layout’s base font size.

Each missing dimension defaults independently to 1em. Omitting both produces a 1em × 1em object; specifying only the width does not derive the height automatically from a resource aspect ratio.

link

Describes a range of visible text as a link object. The enclosed text is laid out normally and receives the named link style by default. Label and GUI components select link:hover and link:active in response to input without reshaping the text. See Interaction messages for the messages produced by link input.

<ul><link id=website src=https://www.defold.com>www.defold.com</link></ul>
<link id=inventory style=menu_link action=open_inventory item=sword>Iron sword</link>

The component tracks each link’s pointer state. It applies link:hover while the pointer is over the link and link:active while the pointer is pressed. When neither state applies, the component restores the style named by the link’s style attribute, or link when the attribute is absent.

Interaction messages

Link interaction uses Defold’s normal input system. Add a Mouse Trigger binding for MOUSE_BUTTON_LEFT, which also enables single-touch input, and acquire input focus in the game object’s script or GUI script:

function init(self)
    msg.post(".", "acquire_input_focus")
end

See Input focus and Mouse and touch input for setup details.

When a label or GUI component receives pointer input, links produce the following messages. Label messages are sent to the owning game object; GUI messages are sent to the GUI script.

Each message contains these fields:

function on_message(self, message_id, message)
    if message_id == hash("text_object_clicked") then
        assert(message.type == hash("link"))
        print(message.id, message.src)
    end
end

Named styles

Each font collection contains render-only named object styles. A link uses the style named by its style attribute, or link when the attribute is absent. There is no general <style> span tag.

Defold provides the following defaults:

Define a style with a text string containing opening tags. The tags are implicitly closed in reverse order, so closing tags and visible text are not allowed.

font.set_style("/fonts/ui.fontc", "link",
    "<color=#2673ff><outline color=#000000 size=1>")

font.set_style("/fonts/ui.fontc", "link:hover",
    "<color=#66b3ff><shake amplitude=0.2 hz=20>")

Tags are applied from left to right, as though they were nested around the object text. A caller-selected object style is applied after the default style. When multiple tags set the same render property, the value applied later overrides earlier values. Effects are appended in left-to-right order.

Layout object API

Use label.get_layout_objects() or gui.get_layout_objects() to retrieve the sprite and link objects from laid-out text.

label.get_layout_objects()

objects = label.get_layout_objects(url)

gui.get_layout_objects()

objects = gui.get_layout_objects(node)

Both functions return a newly created array containing the current layout objects in source order. They return an empty array when the text contains no object tags. Since the objects and their attributes are copied into Lua on every call, cache the result and query again after changing the text or another property that changes its layout.

Returned object fields

Lua example

local text = [[
Read the <link src=https://defold.com/manuals/ id=manual>manual</link>
or inspect <sprite src=images/info.png width=2em/> for more information.
]]

label.set_text("#label", text)

local objects = label.get_layout_objects("#label")
for _, object in ipairs(objects) do
    if object.type == "link" then
        print("link", object.attributes.src)
        print("visible range", object.text_offset, object.text_length)
        print("position", object.x, object.y)
    elseif object.type == "sprite" then
        print("sprite", object.x, object.y, object.width, object.height)
        pprint(object.attributes)
    end
end

local gui_objects = gui.get_layout_objects(gui.get_node("rich_text"))

Useful combinations

Colored outline with a horizontal gradient

<outline size=2 color=#101820>
    <gradient left=#FEE715 right=#FF6F61>Gradient title</gradient>
</outline>

The gradient multiplies the face color only; the outline keeps its own color.

Shake a sentence, gradient one word

<shake hz=20 amplitude=0.5>
    This <gradient left=#FF00FF right=#FFFFFF>whole</gradient> text shakes!
</shake>

The outer position effect applies to every glyph. The nested color effect applies only to “whole”.

Override one property without losing the others

<color=#FFFFFF><outline size=2 color=#000000>
    Normal <color=#FF4040>warning</color> normal
</outline></color>

The inner color changes the face while retaining the inherited outline width and color.