Text formatting tags

ArcGIS Pro text formatting tags allow you to modify the formatting for a portion of text. This allows you to create mixed-format text in which, for example, one word in a sentence is underlined. Text formatting tags can be used almost anywhere text is placed on or around the map. You can use the tags anywhere you can specify both a text string and a text symbol. For example, you can use tags in dynamic label expressions, annotation, legend text, map titles, dynamic text, and the values of fields used to label features. Tags aren't resolved by the Contents pane, by the table view, or in pop-ups, so tags added to field values are visible as tags in those areas.

View a table of the available text formatting tags

Dynamic text is another type of formatting tag, which changes graphic text dynamically based on the current value of its respective property. Dynamic text tags can be used together with text formatting tags to create dynamic mixed-format text on the page layout.

Learn more about working with dynamic text

Formatting tag syntax

Formatting tags have different syntax depending on where they are used. The following examples provide syntax for Annotation and Labeling. The Annotation syntax applies to text in the page layout, the values of fields used to label features and for annotation. The Labeling syntax applies to dynamic label expressions. In all of the Labeling syntax examples, the formatted text can be replaced by a label field.

In annotation, the tags are concatenated to the text string with no special characters:

Annotation
 <BOL>Text</BOL>

In label expressions, the formatting tags must be surrounded by double quotation marks and concatenated to other parts of the expression using the concatenation operator. This operator changes depending on the language used. Arcade, JScript, and Python use the plus (+) operator, while VBScript uses the ampersand (&) operator.

Label Expression - Arcade
 "<BOL>" + "Text" + "</BOL>"
"<BOL>" + $feature.LABELFIELD + "</BOL>"
Label Expression - VBScript
 "<BOL>" & "Text" & "</BOL>"
"<BOL>" & [LABELFIELD] & "</BOL>"

You can use values from a field to populate the formatting tag values:

Label Expression - Arcade
 "<FNT size= '" + $feature.Size + "'>" + "Text" + "</FNT>"
"<FNT size= '" + $feature.Size + "'>" + $feature.LABELFIELD + "</FNT>"
Label Expression - VBScript
 "<FNT size= '" & [Size] & "'>" & "Text" & "</FNT>"
"<FNT size= '" & [Size] & "'>" & [LABELFIELD] & "</FNT>"

Learn more about building label expressions

The following syntax rules apply to formatting tags in ArcGIS Pro:

  • The ArcGIS Pro text formatting tags adhere to XML syntax rules. Each start tag must be accompanied by an end tag. Tags can be nested, but you must close the inner tag before closing an outer tag.

    Annotation
    <BOL><UND>Text</UND></BOL>
    Label Expression
    "<BOL><UND>" + $feature.LABELFIELD + "</UND></BOL>"

  • Formatting tags use a period as a decimal separator. They do not use the locale-specific character.

    Annotation
    <FNT size = "12.5">Textgröße = 12,5</FNT>
    Label Expression
    "<FNT size = '12.5'>" + "Textgröße = 12,5" + "</FNT>"

  • Tag attributes can be surrounded by either single or double quotation marks. The following statements are equivalent:

    Annotation
    <FNT name='Arial' size='18'>My text</FNT>
    <FNT name="Arial" size="18">My text</FNT>
    Label Expression
    '<FNT name="Arial" size="18">' + $feature.LABELFIELD + '</FNT>'
    "<FNT name='Arial' size='18'>" + $feature.LABELFIELD + "</FNT>"

  • The case of tag pairs must match exactly. Therefore, <BOL>...</BOL> is valid, as is <bol>...</bol>, but <Bol>...</bol> is invalid.
  • Any unrecognized, balanced tag pairs are ignored by the parser. For example, even though <notag> is not a valid ArcGIS Pro formatting tag, the following string is valid and will be displayed properly:

    Annotation
    <notag><BOL>State College<BOL></notag>
    Label Expression
    "<notag><BOL>" + "State College" + "<BOL></notag>"

  • The ampersand (&) and angle bracket (<) are special characters and are not valid in your text if formatting tags are used. Use the equivalent character codes &amp; and &lt; instead.

    Annotation

    Instead of <ITA>John & Paul</ITA>, use the following:

    <ITA>John &amp; Paul</ITA>
    Label Expression

    This expression displays the values of the label field inside < > characters:

    "<ITA>&lt;" + $feature.LABELFIELD + "></ITA>"

  • If you have special characters embedded in the values of the label field, you can replace them dynamically using a simple label script.

    Label Expression - Arcade
    "<BOL>" + replace($feature.Notes, "&", "&amp;") + "</BOL>"
    Label Expression - VBScript
    Function FindLabel ([LABELFIELD])
      NewString = Replace([LABELFIELD],"&","&amp;")  
      FindLabel = "<ITA>" & NewString & "</ITA>"
    End Function

  • Every piece of text on a map has a symbol that is used when it is drawn. Formatting tags work by temporarily modifying this base text symbol and drawing the specified portion of the text with the formatting specified in the tag. The buttons and commands on the Labeling ribbon and on the Label Class pane's Symbol tab always reflect the properties of the base text symbol for the selected piece of text and do not reflect modifications made using formatting tags. For example, if you use the <FNT> tag to change the font of a piece of text, the Font drop-down list on the Labeling ribbon does not reflect this change when the label is displayed on the map; it shows you the font of the text's base symbol.
  • Tags have no effect on a piece of text if they simply repeat an existing property of the base text symbol. Generally, this behavior is intuitive; for example, if you have a <BOL> tag in your text string but the base text symbol is already bold, the <BOL> tag in your string has no effect. Also, because tags follow XML rules, you can't use a </BOL> tag to turn off the bold property of a base text symbol. Instead, you can use the <_BOL> tag for this purpose.

    Annotation
    This is bold if the base text symbol is bold <_BOL>, but this is not: </_BOL>
    Label Expression
    "This is bold if the base text symbol is bold <_BOL>, but this is not: </_BOL>"

Use text formatting tags with Maplex Label Engine formatting parameters

Text formatting tags are designed to override the properties assigned to the text symbol of a label class. The Maplex Label Engine detects text formatting tags during the label placement process. Because text formatting tags dictate a label's appearance and override formatting parameters, the Maplex Label Engine switches off its formatting parameters for a label class in some cases when it detects a text formatting tag in a label string.

The following are situations in which text formatting tags are either ignored or change the behavior of the Maplex Label Engine:

  • Font reduction behavior in the Maplex Label Engine is turned off when a label has either a font size or leading text formatting tag.
  • Labels containing text formatting tags are not abbreviated by the Maplex Label Engine when using an abbreviation dictionary.
  • Labels are not dynamically stacked if the label expression contains the base text formatting tag or composite callout part text formatting tag. You can still stack using scripting.

If some labels from a label class have text formatting tags but none of them are present in the current map extent, no text formatting tags are detected, and the text formatting tag restrictions above do not come into effect.

Additional text formatting tags supported with the Maplex Label Engine

The Maplex Label Engine provides an additional unique tag: Base.

"<BSE>" + $feature.FIELDNAME + "</BSE>"

When multiple label fields are used to label a feature, it is necessary to designate which label is the key or base label. The base label is used for the placement strategies, and the other labels are placed in relation to the base label.

The Base tag is only supported by the Maplex Label Engine. If the Standard Label Engine encounters the <BSE> tag, the <BSE> tag is ignored and removed before the label is placed.

As an example, the label classes in the following image have a placement location of Right of point, so the labels are placed due east of the point features. By associating the Base tag label with the first line in the label expression, you control how the complete label expression is placed relative to the feature. The label on the left does not use the Base tag, while the label on the right has the Base tag around the first line of the label.

"<BSE>" + $feature.Name + "</BSE>" + TextFormatting.NewLine + $feature.Prov

<BSE> formatting tag example

Additional tips for building label expressions

The following tips will help you build label expressions:

  • To check the validity of label expressions containing text formatting tags, use Apply to apply your changes and view the labels on the map. In the case of invalid formatting tags or syntax, tags appear as plain text in the map labels.
  • Tags are not interpreted by Arcade, Python, VBScript, or JScript. Instead, they are passed to the ArcGIS Pro framework as plain text to be dynamically formatted as they are drawn. You don't need to quote tags included inside quoted strings.
    "Current <BOL>status</BOL> of parcel: " + $feature.LABELFIELD
  • Formatting tags can be embedded in the values of the field you use to label a layer's features, whether or not you use a label expression. In this way, you can change the format of any portion of a particular value in a label field. To embed formatting tags, the label field must be of string type. Tags and tag attributes used in field values do not need to be surrounded by quotation marks or use concatenation operators, so the following are valid values for a label field:
    <ITA>Rochester</ITA>
    <FNT size='14'>C</FNT>olorado
    <CLR red = '255'>Paul &amp; Mary</CLR>

Available text formatting tags

The following formatting elements and tags are supported in ArcGIS Pro. Click the links in the table to go to the full reference. Annotation and Labeling syntax examples are included for each tag. The Annotation syntax applies to text in the page layout, the values of fields used to label features and for annotation. The Labeling syntax applies to dynamic label expressions. In all of the Labeling syntax examples, the formatted text can be replaced by a label field.

Font name and/or font size

<FNT></FNT>

AttributesNotes

name = {TrueType font}, style = {Font style}, named_instance = {Variable font pre-set}, size = {1}, scale = {1-}

To define a standard font, set name, style, size, scale, or all of them.

For variable fonts, the axes can be specified through tag attributes. The variation tags available for a font, alongside the style, can be found by hovering over the variation axes. Tags for common axes include wght (weight), wdth (width), slnt (slant), ital (italic) and opsz (optical size).

The named_instance can be used to set convenient presets of these variations.

To define a variable font, you must set the name, style, and variations. Variations can be specified through named instances or axes, for example, wght.

Hover over the variation axis name to get the style, instance name, and axis tag name.
Note:

Label example:

"<FNT name = 'Work Sans' style = 'italic' named_instance = 'bold italic' wght = '700'>" + "Text weight = 700" + "</FNT>"

Annotation example:

<FNT name = "Work Sans" style = "italic" named_instance = "bold italic" wght = "700" >Text weight = 700</FNT>

Output example

Font example

Annotation syntax

<FNT name = "Arial" style = "Regular" size = "12">Text size = 12</FNT> <FNT name = "Arial" scale="200"> Text scale = 200</FNT>

Labeling syntax

"<FNT name = 'Arial' style = 'Regular' size = '12'>" + "Text size = 12" + "</FNT>" + "<FNT name = 'Arial' scale='200'>" + "Text scale = 200" + "</FNT>"

Color (RGB)

<CLR></CLR>

AttributesNotes

red, green, blue = {0–255}

alpha = {0–100}

The alpha value is the opacity of the text.

Missing red, green, blue attributes assumed = 0

Missing alpha attribute assumed = 100

Output example

Color (RGB) example

Annotation syntax

<CLR red = "255">Text</CLR>

Labeling syntax

"<CLR red = '255'>" + "Text" + "</CLR>"

Color (CMYK)

<CLR></CLR>

AttributesNotes

cyan, magenta, yellow, black

alpha = {0–100}

The alpha value is the opacity of the text.

Missing attributes assumed = 0

Missing alpha attribute assumed = 100

Output example

Color (CMYK) example

Annotation syntax

<CLR magenta = "100">Text</CLR>

Labeling syntax

"<CLR magenta = '100'>" + "Text" + "</CLR>"

Color (SPOT)

<CLR></CLR>

AttributesNotes

spotname, alpha = {0–100}, tint = {0–100}

cyan, magenta, yellow, black

red, green, blue

Used to specify a spot color for use in printing.

The alpha value is the opacity of the text. It is recommended that you leave the opacity at fully opaque unless you have specific instructions from your print service provider.

The tint value is the relative amount of ink (the darkness).

Alternative color is used to display the spot color on screen and on any output device that does not support spot colors. This color is specified using RGB or CMYK values that are visually similar to the spot color ink.

Missing alpha attribute assumed = 100

Missing tint attribute assumed = 100

Missing attributes assumed = 0

Output example

Color (SPOT) example

Annotation syntax

<CLR spotname = "RedlandsRed" cyan = "38" magenta = "100" yellow = "100" black = "0" alpha = "100" tint = "100">Text</CLR>

Labeling syntax

"<CLR spotname = 'RedlandsRed' cyan = '38' magenta = '100' yellow = '100' black = '0' alpha = '100' tint = '100'>" + "Text" + "</CLR>"

Bold

<BOL></BOL>

Output example

Bold example

Annotation syntax

<BOL>Text</BOL>

Labeling syntax

"<BOL>" + "Text" + "</BOL>"

Italic

<ITA></ITA>

Output example

Italic example

Annotation syntax

<ITA>Text</ITA>

Labeling syntax

"<ITA>" + "Text" + "</ITA>"

Underline

<UND></UND>

Output example

Underline example

Annotation syntax

<UND>Text</UND>

Labeling syntax

"<UND>" + "Text" + "</UND>"

All capitals

<ACP></ACP>

Output example

All capitals example

Annotation syntax

<ACP>Text</ACP>

Labeling syntax

"<ACP>" + "Text" + "</ACP>"

Small capitals

<SCP></SCP>

Output example

Small capitals example

Annotation syntax

<SCP>Text</SCP>

Labeling syntax

"<SCP>" + "Text" + "</SCP>"

Superscript

<SUP></SUP>

Output example

Superscript example

Annotation syntax

E = mc<SUP>2</SUP>

Labeling syntax

"E = mc" + "<SUP>" + "2" + "</SUP>"

Subscript

<SUB></SUB>

Output example

Subscript example

Annotation syntax

H<SUB>2</SUB>O

Labeling syntax

"H" + "<SUB>" + "2</SUB>" + "O"

Character/Letter spacing

<CHR></CHR>

AttributesNotes

spacing = {1-}

Expressed as the percentage adjustment to regular character/letter spacing; 0 percent means no adjustment.

Output example

Character/Letter spacing example

Annotation syntax

<CHR spacing = "200">Text</CHR>

Labeling syntax

"<CHR spacing = '200'>" + "Text" + "</CHR>"

Character/Letter width

<CHR></CHR>

AttributesNotes

width = {1-}

Expressed as the percentage adjustment to regular character/letter width; 100 percent means no adjustment.

Output example

Character/Letter width example

Annotation syntax

<CHR width = "150">Text</CHR>

Labeling syntax

"<CHR width='150'>" + "Text" + "</CHR>"

Word spacing

<WRD></WRD>

AttributesNotes

spacing = {1-}

Expressed as the percentage of spacing between words; 100 percent means regular spacing.

Output example

Word spacing example

Annotation syntax

<WRD spacing = "200">Extra Word Spacing</WRD>

Labeling syntax

"<WRD spacing = '200'>" + "Extra Word Spacing" + "</WRD>"

Align

<ALIGN></ALIGN>

AttributesNotes

horizontal = {left, right, center, justify}

Horizontal attributes:

  • Left—Positions all lines in a paragraph to be aligned to the left edge of the text area. This is the default.
  • Right—Positions all lines in a paragraph to be aligned to the right edge of the text area.
  • Center—Positions all lines in a paragraph to be centered between both left and right edges of the text area.
  • Justify—Spaces the words for all lines in the paragraph (except the last, incomplete line) so they are stretched from the left to right edges of the text area.

Missing horizontal attribute is ignored.

Output example

Align example

Annotation syntax

The top two lines have no tags. The bottom line is aligned <ALIGN horizontal = "right">to the right.</ALIGN>

Labeling syntax

"The top two lines have no tags." + textformatting.newline + "The bottom line is aligned" + textformatting.newline + "<ALIGN horizontal = 'right'>" + "to the right." + "</ALIGN>"

Line leading

<LIN></LIN>

AttributesNotes

leading = {1-}

leading_type = {extra, exact, multiple}

Expressed as the adjustment to regular line spacing (in points); 0 points means no adjustment.

Leading type:

  • Extra—The leading value is extra points before the paragraph's first line and between each line in the paragraph but not after the last line. Values can be negative to condense lines. This is the default.
  • Exact—The height of all lines exactly match the leading value. This option can condense or separate lines depending on whether the value is smaller or greater than the font size.
  • Multiple—The leading value acts as a multiplier of the line size. Values can be less than 1.

Output example

Line leading example

Annotation syntax

<LIN leading = "25" leading_type = "extra">Text with a leading value of 25 points</LIN>

Labeling syntax

"<LIN leading = '25' leading_type = 'extra'>" + "Text with a leading value of 25 points" + "</LIN>"

Un-bold

<_BOL></_BOL>

Output example

Un-bold example

Annotation syntax

The base text symbol is bold <_BOL> but this part is not.</_BOL>

Labeling syntax

"The base text symbol is bold " + "<_BOL>" + " but this part is not." + "</_BOL>"

Un-italic

<_ITA></_ITA>

Output example

Un-italic example

Annotation syntax

The base text symbol is italic <_ITA> but this part is not.</_ITA>

Labeling syntax

"The base text symbol is italic " + "<_ITA>" + " but this part is not." + "</_ITA>"

Un-underlined

<_UND></_UND>

Output example

Un-underlined example

Annotation syntax

The base text symbol is underlined <_UND> but this part is not.</_UND>

Labeling syntax

"The base text symbol is underlined " + "<_UND>" + " but this part is not." + "</_UND>"

Un-superscript

<_SUP></_SUP>

Output example

Un-superscript example

Annotation syntax

<SUP><_SUP> This text is regular but </_SUP> this text is superscript.</SUP>

Labeling syntax

"<SUP><_SUP>" + "This text is regular but" + "</_SUP>" + " this text is superscript." + "</SUP>"

Un-subscript

<_SUB></_SUB>

Output example

Un-subscript example

Annotation syntax

<SUB><_SUB> This text is regular but </_SUB> this text is subscript.</SUB>

Labeling syntax

"<SUB><_SUB>" + "This text is regular but" + "</_SUB>" + " this text is subscript." + "</SUB>"

Background

<BGD></BGD>

AttributesNotes

red, green, blue = {0–255}

cyan, magenta, yellow, black = {0–100}

alpha = {0–100}

outline_red, outline_green, outline_blue = {0–255}

outline_cyan, outline_magenta, outline_yellow, outline_black = {0–100}

outline_alpha = {0–100}

width = {Double}

padding = {Double}

The alpha value is the opacity of the background.

The outline_alpha value is the opacity of the outline.

The width value is the width of the outline in points.

The padding value is the distance the outline is moved from the edge of the background in points.

Missing red, green, blue attributes assumed = 0

Missing cyan, magenta, yellow, black attributes assumed = 0

Missing alpha and outline_alpha attributes assumed = 100

Output example

Background example

Annotation syntax

<CLR red='255' green='236' blue='0' alpha='100'><BGD red='0' green='0' blue='0' alpha='100'>B</BGD></CLR><CLR red='255' green='255' blue='255' alpha='100'><BGD red='230' green='0' blue='0' alpha='100'>15-33</BGD></CLR>

Labeling syntax

"<CLR red='255' green='236' blue='0' alpha='100'><BGD red='0' green='0' blue='0' alpha='100'>" + "B" + "</BGD></CLR><CLR red='255' green='255' blue='255' alpha='100'><BGD red='230' green='0' blue='0' alpha='100'>" + "15-33" + "</BGD></CLR>"

Vertical Morse Code

<VMC></VMC>

AttributesNotes

x_offset = {1-}

y_offset = {1-}

The x_offset value is the decimal X offset value in points.

The y_offset value is the decimal Y offset value in points.

Available only when using the composite callout type.

Output example

Vertical Morse Code example

Annotation syntax

<VMC>TUS</VMC>

Labeling syntax

"<VMC>" + "TUS" + "</VMC>"

Part

<PART></PART>

AttributesNotes

position = {middle, topleft, top, topright, right, bottomright, bottom, bottomleft, left, floating]

h_align = {left, right, center, justify}

v_align = top, center, baseline, bottom}

x_offset = {1-}

y_offset = {1-}

split_offset = {1}

boxed = {true, false}

The x_offset value is the decimal X offset value in points.

The y_offset value is the decimal Y offset value in points.

The split_offset is the gap between the callout border and any part of the text part intersecting the border measured in points. If it is set to wider than the callout width, none of the associated callout lines draw.

The boxed value is whether to keep the part within the callout with a dividing line to separate it from the middle element.

Available only when using the composite callout type.

Offset and align tags override any symbol settings.

Output example

Parts of a composite callout example

Annotation syntax

<PART position="middle">Middle Element</PART><CLR blue="200"><PART position="top">Top</PART><PART position="topleft">TopL</PART><PART position="topright">TopR</PART><PART position="left">Left</PART><PART position="right">Right</PART><PART position="bottom">Bottom</PART><PART position="bottomleft">BottomL</PART><PART position="bottomright">BottomR</PART><PART position="floating" h_align="center" v_align="center" x_offset="0" y_offset="-10">Floating</PART></CLR>

Labeling syntax

"<PART position='middle'>" + "Middle Element" + "</PART><CLR blue='200'><PART position='top'>Top</PART><PART position='topleft'>" + "TopL" + "</PART><PART position='topright'>" + "TopR" + "</PART><PART position='left'>" + "Left" + "</PART><PART position='right'>" + "Right" + "</PART><PART position='bottom'>" + "Bottom" + "</PART><PART position='bottomleft'>" + "BottomL" + "</PART><PART position='bottomright'>" + "BottomR" + "</PART><PART position='floating' h_align='center' v_align='center' x_offset='0' y_offset='-10'>" + "Floating" + "</PART></CLR>"

Base

<BSE></BSE>

Notes

Marks the base text string used for primary label placement (Maplex Label Engine only).

Output example

Base example

Annotation syntax

<BSE>College Station</BSE>Population: 67890 Median Age: 21.9

Labeling syntax

"<BSE>" + "College Station" + "</BSE>" + TextFormatting.NewLine + "Population: 67890" + TextFormatting.NewLine + "Median Age: 21.9"

Related topics