Specify text for labels

Label text strings are derived from one or more feature attributes. Labels are dynamic, so if feature attribute values change, the labels also change. When you turn on labeling, features are initially labeled based on one field; for example, on a meteorological map, you might label weather stations with daily precipitation. This single field-based label is set on the Labeling tab.

Note:

This label field defaults to the first field of string type that contains the text Name in its name (not case sensitive). If no field with that text in its name exists, it defaults to the first field of string type, then the first field of integer type, then the first field of any type.

You can add attribute fields to labels. For example, you can label weather stations with both daily precipitation and maximum wind speed. Whether the labels are based on one attribute field or many fields, the statement that determines the label text is called the label expression. Each label class has its own label expression.

Learn more about creating label expressions

You can insert custom text in the label expression to have it appear with the labels on the map. For example, on a weather map, you can add abbreviated measurement units to each label (for example, in for inches and MPH for miles per hour). You can also use ArcGIS Arcade, Python, VBScript, or JScript in a label expression to change how the text is displayed. For example, you can insert a function to make precipitation values appear on one line of text and wind speed values appear on a second line. These examples are shown in the following image:

You can further control how text appears on the map using ArcGIS Pro text formatting tags. Using text formatting tags, you can specify different text display properties for different portions of the label text. For example, you can show precipitation values with italicized, blue text and wind speed values in regular, black text as shown in the following image:

Label expressions

Using an advanced label expression, you can add any Arcade, Python, VBScript, or JScript logic to label expressions, including conditional logic and looping. For example, you can produce labels that have only the first letter of each word capitalized, regardless of how the text strings are stored in the attribute fields. You can also use label expressions to adjust the formatting of labels using ArcGIS Pro formatting tags. These are special characters for changing the appearance of all or part of a label. For example, you can use the bold formatting tag to make the first line bold in a stacked, multiline label.

Tip:

Arcade expressions are used throughout ArcGIS. The Labeling profile is used for label expressions. Arcade expressions work in ArcGIS Pro and ArcGIS Maps SDKs for Native Apps, where other expression languages may not be supported.

Note:

With Windows 11, version 24H2, VBScript becomes a feature on demand and requires the VBScript capability.

Do one of the following:

• Convert the expression type to Python or Arcade.
• Enable the VBScript optional feature in the Windows system settings.

A label expression can be either a simple single-line expression or a more complex expression spanning multiple lines of code and using the parser's programming logic. Arcade enables complex expressions by default. When using Python, VBScript, or JScript, check the Advanced check box and wrap the code in a function to enable multiline expressions.

If you have coded value descriptions in your data, you can use the Use coded value descriptions option to display those descriptions in the label instead of the code.

Field values are automatically cast to text strings. Consequently, to use a numeric value in an arithmetic operation or when making a comparison, you must cast it back to a numeric data type.

Note:

NULL values are not cast to text strings. They are passed to the expression as NULL.

When using Arcade, the field values maintain their data type.

The following examples add two integer fields:

Arcade

$feature.FIELD1 + $feature.FIELD2

Python

int([FIELD1]) + int([FIELD2])

VBScript

cint([FIELD1]) + cint([FIELD2])

JScript

parseInt([FIELD1]) + parseInt([FIELD2])

Additional Maplex Label Engine options

When using the Maplex Label Engine, you can control the white space used in a label.

The Remove extra spaces option removes additional space characters from the label text. These extra spaces include all preceding, succeeding, and interior space characters. If the option is disabled, the spaces are used for formatting, for example, allowing you to indent text in a stacked label.

The Remove extra line breaks option removes additional line breaks from the label text. If the option is disabled, multiline spacing is possible in a stacked label.

Write a label expression

To write a label expression, complete the following steps:

1. Ensure that List By Labeling is the active method of displaying the Contents pane. Click the List By Labeling tab .
2. Choose a label class in the Contents pane and click the Labeling tab.
3. On the Labeling tab, in the Label Class group, click the Expression button .
4. Choose a language from the Language menu.
5. Type an Arcade, Python, VBScript, or JScript expression.

   You can also create an expression by double-clicking the field to add it to the expression or by selecting the field, right-clicking, and choosing Append to append the field into the clicked location, separated by a space or spaces. Use provided text functions by double-clicking to add them to the expression.

   When using Python, VBScript and JScript fields are enclosed in square brackets [ ] irrespective of the data type of the layer's data source. Arcade uses a different way to specify fields.

   Field syntax

   $feature.fieldname

   Joined field syntax

   $feature['tablename.fieldname']

   Coded value domain field syntax

   DomainName($feature, 'fieldname')

   Tip:

   When using Arcade, you can use the Console function to assist in debugging label expressions. When you click Verifiy , a View console messages link appears if the Console function is included in the expression. Click this link to open the Console Messages window. You can also provide a title for the expression when using Arcade.

   Caution:

   When labeling a field when the name contains special characters or starts with a number, Arcade uses the same format as joined field syntax, for example, $feature['33field'], $feature['acres²'], $feature['st_area(SHAPE)'].

   Caution:

   When using a backward slash in a label expression, you need to escape it using a second backward slash. For example, "C:\\Project\\" + $feature.ProjectId" will label as C:\Project\2. When using Arcade, you can also replace the backward slash with TextFormatting.BackwardSlash.

   Optionally, enter ArcGIS Pro text formatting tags in the Expression box to apply formatting to a portion of the label text.

   Note:

   When using Arcade, field formatting from the layer is not used for the labels. Arcade formatting methods must be used.

   If the expression will span multiple lines of code, check the Advanced check box and enter the label expression. This is not necessary when using Arcade.

6. Click Verify to ensure that there are no syntax errors, and click Apply.

   If there are syntax errors, the line number and reason are referenced in the error. To see these numbers, right-click the label expression input box and select Show Line Numbers.

   Both regular and advanced label expressions can be exported as label expression files (.lxp), which can be loaded into other layers or maps.

Expression examples

Label expression examples are shown in the subsections below.

Concatenate a string to a field value

Concatenate a string to the value in a field. For example, the following expression creates a label in which the value of the PARCELNO field is preceded by the text "Parcel no:":

Arcade

"Parcel no: " + $feature.PARCELNO

Python

"Parcel no: " + [PARCELNO]

VBScript

"Parcel no: " & [PARCELNO]

JScript

"Parcel no: " + [PARCELNO]

Round a decimal number

Round a decimal number to a set number of decimals. For example, the following expression displays an AREA field rounded to one decimal place:

Arcade

round(number($feature.AREA), 1)

Python

round(float([AREA]), 1)

VBScript

Round ([AREA], 1)

JScript

function FindLabel ( [AREA] )
{
var ss;
var num= parseFloat([AREA]);
ss =  num.toFixed(1);
  return (ss);
}

Convert to uppercase and lowercase

Convert text labels to all uppercase or lowercase. For example, the following expression makes the NAME field all lowercase:

Arcade

lower($feature.NAME)

Python

def FindLabel ( [NAME] ):
  S = [NAME]
  S = S.lower()
  return S

VBScript

LCase ([NAME])

JScript

[NAME].toLowerCase()

Convert to proper case

Convert text labels to proper case. For example, the following expression takes a NAME field that is uppercase and makes it proper case:

Arcade

Proper($feature.NAME, 'firstword')

Python

def FindLabel ( [NAME] ):
  S = [NAME]
  S = S.title()
  return S

VBScript

Function FindLabel ( [NAME] )
FindLabel = UCase(Left([NAME],1)) & LCase(Right([NAME], Len([NAME]) -1))
End Function

JScript

function FindLabel ( [NAME] )
{
var str = [NAME];
var iLen = String(str).length;
var upper = (str.substring(0,1)).toUpperCase();
var lower = (str.substring(1, iLen)).toLowerCase()
return upper + lower;
}

Stack text from multiple fields

Create stacked text. For example, the following expression creates a label with the NAME field and the ADDRESS field on separate lines:

Arcade

$feature.NAME + TextFormatting.NewLine + $feature.ADDRESS

Python

[NAME] + '\n' + [ADDRESS]

VBScript

[NAME] & vbCrLf& [ADDRESS]

JScript

[NAME] + "\r" + [ADDRESS]

Stack text from one field

Create stacked text based on text from one field. For example, the following expression uses the comma to specify where the stack occurs:

Arcade

replace($feature.LABELFIELD, ', ', '\n')

Python

def FindLabel ( [LABELFIELD] ):
  S = [LABELFIELD]
  S = S.replace(', ', '\n')
  return S

VBScript

Function FindLabel ( [LABELFIELD] )
FindLabel = replace([LABELFIELD], ", ", vbnewline)
End Function

JScript

function FindLabel ( [LABELFIELD] )
{
var r, re;
var str = [LABELFIELD];
re = /,/g;
r = str.replace(re, "\r");
return r;
}

Format labels

Format the labels. For example, the following expression displays the label as currency:

Arcade

"Occupancy Revenue: $" + round($feature.MAXIMUM_OC * $feature.RATE, 2)

Python

def FindLabel ( [MAXIMUM_OC], [RATE] ):
  import locale
  locale.setlocale(locale.LC_ALL, '')
  S = locale.currency(float([MAXIMUM_OC]) * float([RATE]))
  return S

VBScript

"Occupancy Revenue: " & FormatCurrency ([MAXIMUM_OC] * [RATE])

JScript

function FindLabel ( [MAXIMUM_OC], [RATE] )
{
var ss;
var num1 = parseFloat([MAXIMUM_OC]);
var num2 = parseFloat([RATE]);
var num3 = num1 * num2
ss =  num3.toFixed(2);
  return ("$" + ss);
}

Label with part of the string

Use only part of the field as the label. For example, the following expression displays the third through fifth characters:

Arcade

mid($feature.LABELFIELD, 2, 3)

Python

def FindLabel ( [LABELFIELD] ):
  S = [LABELFIELD]
  return S[2:5]

VBScript

Mid([LABELFIELD], 3, 3)

JScript

function FindLabel ( [LABELFIELD] )
{
var S;
var str = [LABELFIELD];
S = str.substring(2, 5);
return S;
}

Create a conditional if-else statement

Specify a conditional if-else statement. These functions label cities with their name in a large, red font if their population is equal to or exceeds 250,000 or in the default label font if the population is less than 250,000:

Arcade

if ($feature.POPULATION >=250000) {
    return "<CLR red='255'><FNT size = '14'>" + $feature.NAME + "</FNT></CLR>"
}
else {
    return $feature.NAME
}

Python

def FindLabel ( [NAME], [POPULATION] ):
  if int([POPULATION]) >= 250000:
    return "<CLR red='255'><FNT size = '14'>" + [NAME] + "</FNT></CLR>"
  else:
    return [NAME]

VBScript

Function FindLabel ([NAME], [POPULATION])
  if (cLng([POPULATION]) >= 250000) then
   FindLabel = "<CLR red='255'><FNT size = '14'>" + [NAME] + "</FNT></CLR>"
  else
	 FindLabel = [NAME]
  end if
End Function

JScript

function FindLabel ( [NAME], [POPULATION]  )
{
if (parseFloat([POPULATION]) >= 250000){
return ("<CLR red='255'><FNT size = '14'>" + [NAME] + "</FNT></CLR>");
}
else
return ([NAME]);
}

Note:

To label a subset of features based on a field value, create the SQL query in the label class instead of through the label expression.

Additional resources

For additional information, see the following:

• Arcade Language Reference
• Python Language Reference
• Microsoft VBScript Language Reference
• Microsoft JScript Language Reference

Some information from these additional resources is stored on web pages that are not created, owned, or maintained by Esri. Esri does not guarantee the availability of these pages and is not responsible for the content found on them.