ArcGIS Pro text formatting tags allow you to modify the formatting for a portion of text. This allows you to create mixed-format text where, 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:<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."<BOL>" + "Text" + "</BOL>"
"<BOL>" + $feature.LABELFIELD + "</BOL>"
"<BOL>" & "Text" & "</BOL>"
"<BOL>" & [LABELFIELD] & "</BOL>"
You can use values from a field to populate the formatting tag values:"<FNT size= '" + $feature.Size + "'>" + "Text" + "</FNT>"
"<FNT size= '" + $feature.Size + "'>" + $feature.LABELFIELD + "</FNT>"
"<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 may 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 & and < instead.
Annotation Instead of <ITA>John & Paul</ITA>, use:
<ITA>John & Paul</ITA>
Label Expression This expression displays the values of the label field inside < > characters:
"<ITA><" + $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, "&", "&") + "</BOL>"
Label Expression - VBScript Function FindLabel ([LABELFIELD]) NewString = Replace([LABELFIELD],"&","&") 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 where text formatting tags are either ignored or change the behavior of the Maplex Label Engine:
- The character spacing text formatting tag is ignored by the Maplex Label Engine. Character spacing (letter spacing) must be set in the text symbol to be respected.
- The word spacing text formatting tag is ignored by the Maplex Label Engine. Word spacing must be set in the text symbol to be respected.
- 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 offers 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
Additional tips for building label expressions
The following tips will help you build your 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 & 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.
Element | Output |
---|---|
| |
| |
| |
| |
| |
|
Font name and/or font size
<FNT></FNT>
Attributes | Notes |
---|---|
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. 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
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>
Attributes | Notes |
---|---|
red, green, blue = {0–255} alpha = {0–100} |
The alpha value is opacity of the text. Missing red, green, blue attributes assumed = 0 Missing alpha attribute assumed = 100 |
Output example
Annotation syntax
<CLR red = "255">Text</CLR>
Labeling syntax
"<CLR red = '255'>" + "Text" + "</CLR>"
Color (CMYK)
<CLR></CLR>
Attributes | Notes |
---|---|
cyan, magenta, yellow, black alpha = {0–100} | The alpha value is opacity of the text. Missing attributes assumed = 0 Missing alpha attribute assumed = 100 |
Output example
Annotation syntax
<CLR magenta = "100">Text</CLR>
Labeling syntax
"<CLR magenta = '100'>" + "Text" + "</CLR>"
Color (SPOT)
<CLR></CLR>
Attributes | Notes |
---|---|
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
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
Annotation syntax
<BOL>Text</BOL>
Labeling syntax
"<BOL>" + "Text" + "</BOL>"
Italic
<ITA></ITA>
Output example
Annotation syntax
<ITA>Text</ITA>
Labeling syntax
"<ITA>" + "Text" + "</ITA>"
Underline
<UND></UND>
Output example
Annotation syntax
<UND>Text</UND>
Labeling syntax
"<UND>" + "Text" + "</UND>"
All capitals
<ACP></ACP>
Output example
Annotation syntax
<ACP>Text</ACP>
Labeling syntax
"<ACP>" + "Text" + "</ACP>"
Small capitals
<SCP></SCP>
Output example
Annotation syntax
<SCP>Text</SCP>
Labeling syntax
"<SCP>" + "Text" + "</SCP>"
Superscript
<SUP></SUP>
Output example
Annotation syntax
E = mc<SUP>2</SUP>
Labeling syntax
"E = mc" + "<SUP>" + "2" + "</SUP>"
Subscript
<SUB></SUB>
Output example
Annotation syntax
H<SUB>2</SUB>O
Labeling syntax
"H" + "<SUB>" + "2</SUB>" + "O"
Character/Letter spacing
<CHR></CHR>
Attributes | Notes |
---|---|
spacing = {1-} | Expressed as the percentage adjustment to regular character/letter spacing; 0 percent means no adjustment. |
Output example
Annotation syntax
<CHR spacing = "200">Text</CHR>
Labeling syntax
"<CHR spacing = '200'>" + "Text" + "</CHR>"
Character/Letter width
<CHR></CHR>
Attributes | Notes |
---|---|
width = {1-} | Expressed as the percentage adjustment to regular character/letter width; 0 percent means no adjustment. |
Output example
Annotation syntax
<CHR width = "150">Text</CHR>
Labeling syntax
"<CHR width='150'>" + "Text" + "</CHR>"
Word spacing
<WRD></WRD>
Attributes | Notes |
---|---|
spacing = {1-} | Expressed as the percentage of spacing between words; 100 percent means regular spacing. |
Output example
Annotation syntax
<WRD spacing = "200">Extra Word Spacing</WRD>
Labeling syntax
"<WRD spacing = '200'>" + "Extra Word Spacing" + "</WRD>"
Align
<ALIGN></ALIGN>
Attributes | Notes |
---|---|
horizontal = {left, right, center, justify} | Horizontal attributes:
Missing horizontal attribute is ignored. |
Output 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>
Attributes | Notes |
---|---|
leading = {1-} leading_type = {extra, exact, multiple} | Expressed as the adjustment to regular line spacing (in points); 0 points means no adjustment. Leading type:
|
Output 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
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
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
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
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
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>
Attributes | Notes |
---|---|
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 opacity of the background. The outline_alpha value is 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
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>
Attributes | Notes |
---|---|
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
Annotation syntax
<VMC>TUS</VMC>
Labeling syntax
"<VMC>" + "TUS" + "</VMC>"
Part
<PART></PART>
Attributes | Notes |
---|---|
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
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 base text string used for primary label placement (Maplex Label Engine only). |
Output 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"