UI escape sequences

Main Menu
WoW API Lua API FrameXML util Widget API Widget scripts XML schema Events CVars Macro commands Combat Log Escape sequences Hyperlinks API changes HOWTOs wowuidev

→ UI Tech. Details

Many UI elements that display text on the screen support a special escape sequences starting with the | pipe character.

Warning: If you are using the chat window or an in-game text editor, then "|" will most likely be replaced with "||". Try using "\124" instead of "|". 124 is the ASCII code escape for the pipe character, and will work regardless of what the editor is trying to do.

Escape Sequences

Coloring

|cAARRGGBBtext|r

• Each pair of digits represents a color value (plus the alpha value, however the alpha value is currently ignored and should always be FF) as a hexadecimal number. The |r escape sequence pops nested color sequences in-order.

/run print("this is \124cFFFF0000red and \124cFF00FF00this is green\124r back to red\124r back to white")
> this is red and this is green back to red back to white

Classic

Patch 1.13.2 (2019-08-26): The |r escape sequence resets the text to the default color instead of popping nested colors in-order.

/run print("this is \124cFFFF0000red and \124cFF00FF00this is green\124r back to white")
> this is red and this is green back to white

Textures

|Tpath:height[:width[:offsetX:offsetY:[textureWidth:textureHeight:leftTexel:rightTexel:topTexel:bottomTexel[:rVertexColor:gVertexColor:bVertexColor]]]]|t

Will insert a texture into a font string. Parameter width is optional (see below). The offsets are optional and will shift the texture from where it would normally be placed. TextHeight is based on size of the font used - this is used to automatically scale icons based on the size of the text.

• height == 0; width omitted: Width = Height = TextHeight (always square!)
• height > 0;  width omitted: Width = Height = height (always square!)
• height == 0; width == 0   : Width = Height = TextHeight (always square!)
• height > 0;  width == 0   : Width = TextHeight; Height = height (height is height!!!)
• height == 0; width > 0    : Width = width * TextHeight; Height = TextHeight (width is an aspect ratio and defines width!!!)
• height > 0;  width > 0    : Width = width; Height = height
• offsetX offsetY: Offset for the rendered image, in pixels
• textureWidth textureHeight: Size of the source image, in pixels
• leftTexel rightTexel topTexel bottomTexel: (x1 x2 y1 y2) Coordinates that identify the left/right/top/bottom edges, in pixels (see Texture:SetTexCoord() but non-normalized)
• rVertexColor gVertexColor bVertexColor: RGB color values in the range 0-255 that are used to tint the texture

Notes:

• When you need to display a square icon in the string (spell/item icon), use only |Tpath:0|t
• When you need to display a rectangular image in the string (Blizzard logo), use aspect ratio version: |Tpath:0:aspectRatio|t

Texture atlas

Main article: AtlasID

Atlases allow for easily getting part of a texture without having to use tex coords.

|Aatlas:height:width[:offsetX:offsetY]|a

Examples

Coloring
"|cFFFF0000This is red text|r this is normal color" WrapTextInColorCode("This is red text", "FFFF0000")	This is red text this is normal color
Texture
The file path or FileDataID can be used. Both slash / or escaped backslashes \\ are valid file separators. "|T133784:16|t Coins" "|TInterface\\Icons\\INV_Misc_Coin_01:16|t Coins" CreateTextureMarkup("Interface/Icons/INV_Misc_Coin_01", 64, 64, 16, 16, 0, 1, 0, 1)	Coins[1]
Sets the vertex color of the texture to green (73:177:73). "|TInterface\\ChatFrame\\UI-ChatIcon-ArmoryChat:14:14:0:0:16:16:0:16:0:16:73:177:73|t Reckful"	Reckful[2]
Texture atlas
The Atlas name or ID can be used.[3] Parameters can be omitted in between colon characters. "|A:4259:19:19|a Tank" "|A:groupfinder-icon-role-large-tank:19:19|a Tank" "|Tinterface\\lfgframe\\groupfinder:19:19:::1024:1024:915:944:785:814|t Tank" CreateAtlasMarkup("groupfinder-icon-role-large-tank", 16, 16)	Tank[4]

Utility functions:

• WrapTextInColorCode()
• ColorMixin:WrapTextInColorCode() - Adds the color escape sequences from a ColorMixin.
• CreateTextureMarkup()
• CreateAtlasMarkup()

Protected strings

Also known as Kstrings, they prevent strings from being parsed in addons.

• Battle.net

The q variant e.g. |Kq1|k is used for the confidentiality of Battle.net account names. The number represents the Battle.net friend ID.

Known sources: C_BattleNet.GetAccountInfoByID()

• Group Finder

The r variant e.g. |Kr14|k is used for the name and comment in group finder listings to prevent addons like World Quest Group Finder.

Known sources: C_LFGList.GetSearchResultInfo() and C_LFGList.GetActiveEntryInfo()

• Communities

The v variant e.g. |Kv1|k is used for Community Channels to prevent addons from using it as a shared, persistent data storage. The number represents a chat message line ID.

Known sources: CHAT_MSG_COMMUNITIES_CHANNEL

Grammar

number |1singular;plural;

Will choose a word depending on whether the digit preceding it is 0/1 or not (i.e. 1,11,21 return the first string, as will 0,10,40). Note that unlike |4 singular and plural forms are separated by semi-colon.

|2text

Before vowels outputs d' (with apostrophe) and removes any leading spaces from text, otherwise outputs de (with trailing space)

|3-formid(text)

Displays text declined to the specified form (index ranges from 1 to GetNumDeclensionSets()). Processed by C code, data used for parsing isn't available to UI, all events fire with the data already processed.

number |4singular:plural; -or- number |4singular:plural1:plural2;

Will choose a form based on the number preceding it. Client locale dependant. More than two forms (separated by colons) may be required by some locales (i.e. Russian requires 3 forms), if too many forms provided they are ignored, if needed form isn't provided empty string will be used instead. Note that unlike |1 singular and plural forms are separated by colon. (added with 2.4.2)

Other

|n

Newline, if the widget supports it. Similar behavior as \n

||

Escapes the "|" character.

|

"|" followed by something that is not a valid escape sequence will be displayed as-is or is otherwise undefined behavior.

Hyperlinks

See also: GameTooltip:SetHyperlink() and ExtractHyperlinkString().

Implemented in FrameXML/ItemRef.lua

Hyperlinks are clickable (chat) links.

|cffxxxxxx|HlinkType:payload|h[text]|h|r

Each kind of hyperlink has the following format:

Text	Description
|cffxxxxxx	The color code
|H	Begins the hyperlink
linkType:payload	The link type and any colon-delimited payload
|h	Marks the end of the payload
[text]	Localized display text
|h	Ends the hyperlink
|r	Stops coloring

The server may expect certain combinations of color, payload and text as SendChatMessage() can reject invalid entries.

HOWTO: Inspecting a hyperlink
From the in-game chat window /dump "[Flash Heal]" > "|cff71d5ff|Hspell:2061:0|h[Flash Heal]|h|r" From an addon, when clicking a hyperlink in-game hooksecurefunc("SetItemRef", function(link, text) print(link, text:gsub("|", "||")) end) > "spell:139:0", "|cff71d5ff|Hspell:139:0|h[Renew]|h|r"

achievement

See also: AchievementLink

achievement : achievementID : guid : completed : month : day : year : criteria1 : criteria2 : criteria3 : criteria4

• guid The player's GUID.
• completed 1 for earned, 0 for unearned achievements.
• month:day:year Date the achievement was earned or 0:0:-1 if not earned.
• criteria1-4 32-bit bitmask fields for completed criteria, or 0:0:0:0 if not completed.

Example:

"|cffffff00|Hachievement:10671:Player-1096-06DF65C1:1:2:16:17:4294967295:4294967295:4294967295:4294967295|h[Level 110]|h|r"

"|cffffff00|Hachievement:12544:Player-1096-06DF65C1:0:0:0:-1:0:0:0:0|h[Level 120]|h|r"

api

See also: APILink

Shows API Documentation from the /api command.

api : type : name : [parentName]

Example:

"|cffff55dd|Hapi:system:MapUI:|hMapUI|h|r"

"|cff55ddff|Hapi:function:GetMapInfo:MapUI|hC_Map.GetMapInfo()|h|r"

"|cff77ff22|Hapi:event:ZoneChanged:MapUI|hEvent.MapUI.ZoneChanged|h|r"

"|cff55ffdd|Hapi:table:UiMapDetails:MapUI|hUiMapDetails|h|r"

azessence

Azerite Essence link

azessence : essenceID : rank

Example: "|cffa335ee|Hazessence:12:3|h[The Crucible of Flame]|h|r"

See also: C_AzeriteEssence.GetEssenceInfo()

battlepet

battlepet : speciesID : level : breedQuality : maxHealth : power : speed : battlePetID

Example: "|cff1eff00|Hbattlepet:202:25:2:1435:267:240:BattlePet-0-000000CC9EA1|h[Baby Blizzard Bear]|h|r"

battlePetAbil

battlePetAbil : abilityID : maxHealth : power : speed

Example: "|cff4e96f7|HbattlePetAbil:348:1435:267:240|hBash|h|r"

calendarEvent

calendarEvent : monthOffset : monthDay : index

Example: "|HcalendarEvent:0:12:1|hSpring Balloon Festival|h"

See also: C_Calendar.GetDayEvent()

channel

Opens the chat window to a specific /channel.

channel : channelType : [channelID]

Example:

"|Hchannel:channel:2|h[2. Trade - City]|h"

"|Hchannel:PARTY|h[Party]|h"

clubFinder

Guild Finder (8.2.5) invite link.

clubFinder : clubFinderId

Example: "|cffffd100|HclubFinder:ClubFinder-1-19160-1598-53720920|h[Guild: Happy Leveling]|h|r"

See also: GetClubFinderLink()

clubTicket

WoW communities & Blizzard Groups invite link.

clubTicket : ticketId

Example: "|cffffd100|HclubTicket:oxPbMfv2R|h[Join: test]|h|r"

See also: GetClubTicketLink()

community

Community link in Quick Join requests.

community : clubId

conduit

Conduit link

conduit : id : [rank]

Example: "|cff71d5ff|Hconduit:5:1|h[Stalwart Guardian]|h|r"

See also: C_Soulbinds.GetConduitHyperlink()

currency

currency : id : [amount]

Example: "|cffffffff|Hcurrency:1744|h[Corrupted Memento]|h|r"

death

Opens the Death recap overview.

death : recapID

Example: "|Hdeath:1|h[You died.]|h"

enchant

Opens the Tradeskill window for a recipe.

enchant : spellID

Example: "|cffffd000|Henchant:162206|h[Draenor Engineering: World Shrinker]|h|r"

garrfollower

garrfollower : followerID : quality : level : itemLevel : ability1 : ability2 : ability3 : ability4 : trait1 : trait2 : trait3 : trait4 : spec1

Example: "|cffa335ee|Hgarrfollower:856:4:110:900:457:777:0:0:684:758:0:0:354|h[Calia Menethil]|h|r"

garrfollowerability

garrfollowerability : abilityID

Example:

"|cff4e96f7|Hgarrfollowerability:354|h[Discipline]|h|r"

"|cff4e96f7|Hgarrfollowerability:457|h[Holy Nova]|h|r"

garrmission

garrmission : missionID : missionDBID

Example: "|cffffff00|Hgarrmission:1610:000000000238f82d|h[Withered Straining]|h|r"

Note: This link type can also be used for securely implementing custom links by posthooking SetItemRef() since it silently fails on non-numbers, whereas custom link types would error out. It does not work on actual chat messages through SendChatMessage() as the server won't show the message.

hooksecurefunc("SetItemRef", function(link)
	local linkType, addon, param1 = strsplit(":", link)
	if linkType == "garrmission" and addon == "SomeAddon" then
		if param1 == "foo" then
			print(link)
		end
	end
end)

print("|cFFFFFF00|Hgarrmission:SomeAddon:foo|h[Some Clickable Message]|h|r")

instancelock

Opens the /raidinfo list.

instancelock : guid : instanceID : difficulty : defeatedEncounters

• guid The player's GUID.
• instanceID The instance's InstanceID
• difficulty The instance's DifficultyID
• defeatedEncounters Bitfield indicating the encounters that have been defeated. e.g. 7 means that the first 3 encounters have been cleared.

Example: "|cffff8000|Hinstancelock:Player-3296-000957C8:543:2:4|h[Hellfire Citadel: Ramparts]|h|r"

item

item : itemString

• itemString must be minimum 18 params when used in SendChatMessage: i.e. %d:::::::::::::::::

Example:

"|cffffffff|Hitem:2592:::::::::::::::::|h[Wool Cloth]|h|r"

See also: ItemLink

journal

Opens the Adventure Guide.

journal : journalType : journalID : difficulty

• journalType 0=Instance, 1=Encounter, 2=Section.
• journalID InstanceID, EncounterID, or SectionID.
• difficulty DifficultyID of the instance.

Example:

"|cff66bbff|Hjournal:0:1031:14|h[Uldir]|h|r"

"|cff66bbff|Hjournal:1:2147:14|h[G'huun]|h|r"

"|cff66bbff|Hjournal:2:18068:14|h[Titan Spark]|h|r"

See also: EJ_HandleLinkPath()

levelup

levelup : level : levelUpType : [petName]

Example:

"|cffFF4E00|Hlevelup:2:LEVEL_UP_TYPE_CHARACTER|h[Level 2]|h|r"

"|cffFF4E00|Hlevelup:2:LEVEL_UP_TYPE_PET:Bear|h[Level 2]|h|r"

lootHistory

Opens the /loot window.

lootHistory : rollID

player

Left-click: starts a whisper message

Right-click: opens the player context menu

Shift-click: sends a /who query

player : name : [lineID] : [chatType] : [chatTarget]

• lineID Message ID for reporting.

Example:

"|Hplayer:Fadeshift|h[Fadeshift]|h"

"|Hplayer:Aquadoll-MoonGuard|h[Aquadoll]|h"

"|Hplayer:Ketho-Anasterian:8:PARTY:|h[|cfffefefeKetho|r]|h"

"|Hplayer:Kilastra-DefiasBrotherhood:90:CHANNEL:2|h[|cff8686ecKilastra|r]|h"

See also: GetPlayerLink()

playerCommunity

playerCommunity : name : communityClubID : communityStreamID : communityEpoch : communityPosition

Example: "|HplayerCommunity:Ketho-Anasterian:333281:1:1557794365297000:5886997898769|h[|cfffefefeKetho|r]|h"

BNplayer

Battle.net friend links.

BNplayer : name : bnetIDAccount : lineID : chatType : chatTarget

BNplayerCommunity

BNplayerCommunity : name : bnetIDAccount : communityClubID : communityStreamID : communityEpoch : communityPosition

quest

quest : questID : questLevel : unknown1 : unknown2 : unknown3

Example:

"|cffffff00|Hquest:53370:-1:110:120:3|h[Hour of Reckoning]|h|r"

"|cffff8040|Hquest:40746:113:110:255:0|h[One of the People]|h|r"

See also: QuestLink

shareachieve

Opens the Twitter /share window for an achievement.

shareachieve : achievementID : earned

Example: "|cffffd200|Hshareachieve:964:1|h|TInterface\ChatFrame\UI-ChatIcon-Share:18:18|t|h|r"

shareitem

Twitter item link.

shareitem : itemLink : earned

Example: "|cffffd200|Hshareitem:151428::::::::20:257:512:1:1:4068:20::::1|h|TInterface\ChatFrame\UI-ChatIcon-Share:18:18|t|h|r"

sharess

Twitter screenshot link.

sharess : screenshotIndex

• screenshotIndex: index of the screenshot to autofill the Tweet with, counted from last login.

Example: "|cffffd200|Hsharess:1|h|TInterface\ChatFrame\UI-ChatIcon-Share:18:18|t|h|r"

spell

spell : spellId : glyphId : [event]

Example:

"|cff71d5ff|Hspell:2096:0|h[Mind Vision]|h|r"

"|Hspell:589:0:SPELL_DAMAGE|hShadow Word: Pain|h"

See also: GetSpellLink()

storecategory

Opens the In-Game Store.

storecategory : category

Example: "|cffffd000|Hstorecategory:games|h[Click To Upgrade]|h|r"

talent

talent : talentID

Example: "|cff71d5ff|Htalent:21754|h[Circle of Healing]|h|r"

See also: GetTalentInfoByID()

trade

Shows the tradeskill window (from another player).

trade : guid : spellID : skillLineID

• guid The player's GUID.
• spellID The tradeskill's Spell ID.
• skillLineID The TradeSkillLineID.

Example: "|cffffd000|Htrade:Player-3296-000957C8:195128:185|h[Cooking]|h|r"

See also: TradeSkillLink

transmogappearance

transmogappearance : sourceID

transmogillusion

Previews a weapon enchant in the Dressing room.

transmogillusion : sourceID

Example: "|cffff80ff|Htransmogillusion:5862|h[Titanguard]|h|r"

See also: C_TransmogCollection.GetIllusionSourceInfo()

transmogset

transmogset : setID

See also: C_TransmogSets.GetSetInfo()

unit

Shows the unit tooltip. Opens the combat log context menu on right-click.

unit : guid : [name]

Example: "|Hunit:Creature-0-2083-0-7-299-00005A0F91:Young Wolf|hYoung Wolf|h"

Implemented in Blizzard_CombatLog.lua

urlIndex

Opens a URL in the default web browser.

urlIndex : index

Example: "|HurlIndex:25|h|cff006995Frequently Asked Questions|r|h"

worldmap

Opens the World Map to display a pinned waypoint.

 worldmap : uiMapID : x : y

• uiMapID The UiMapID for the waypoint.
• x The X coordinate of the waypoint, multiplied by 10000.
• y The Y coordinate of the waypoint, multiplied by 10000.

Example: "|cffffff00|Hworldmap:84:7222:2550|h[|A:Waypoint-MapPin-ChatIcon:13:13:0:0|a Map Pin Location]|h|r"

enUS globalstring: MAP_PIN_HYPERLINK = "|A:Waypoint-MapPin-ChatIcon:13:13:0:0|a Map Pin Location"

See also: C_Map.SetUserWaypoint()