Back to Top

Specify text for labels

In this topic

  1. Label expressions
  2. Writing a label expression
  3. Expression examples

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 (case insensitive). 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 your labels. For example, you might label your weather stations with both daily precipitation and maximum wind speed. Whether your labels are based on one attribute field or many fields, the statement that determines your label text is called the label expression. Each label class has its own label expression.

Learn more about creating label expressions

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

Label placement example

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 your 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 placement example

Label expressions

Using an advanced label expression, you can add any Arcade, Python, VBScript, or JScript logic to your label expressions, including conditional logic and looping. For example, you could 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 your labels using ArcGIS Pro formatting tags. These are special characters for changing the appearance of all or part of your labels. For example, you might use the bold formatting tag to make the first line bold in a stacked, multiline label.

Tip:
Arcade expressions are used throughout the ArcGIS platform. Arcade expressions work in Runtime, ArcGIS Pro, and ArcGIS Runtime SDKs, while other languages do not.

A label expression can either be a simple single line expression, or a more complex expression spanning multiple lines of code and making use of the parser's programming logic. Arcade enables complex expressions by default. When using Python, VBScript, or JScript, the Advanced checkbox must be checked and the code must be wrapped in a function to enable multi-line 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. Therefore, if you want 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

The Maplex Label Engine provides you the additional ability to control the white space used in your 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.

Writing a label expression

  1. Ensure List By Labeling is the active way of displaying the Contents pane.
  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 Expression Label expression.
  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')

    Caution:

    Do not use variable names that duplicate field names when using Arcade. In this situation, labels are not created.

    When labeling a field where 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)'].

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

    Note:

    When using Arcade, field formatting on the layer is not brought over to the labels. Arcade formatting methods must be used.

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

  6. Click Verify to make sure 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

The following are examples of label expressions:

  • Concatenate a string to the value in a field; for example, this expression creates a label where 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 to a set number of decimals; for example, this 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 your text labels to all uppercase or lowercase; for example, this expression makes a 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 your text labels to proper case; for example, this 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;
}
  • Create stacked text; for example, this expression creates a label with the NAME field and the two address fields all on separate lines:
    Arcade
    "Name: " + $feature.NAME + TextFormatting.NewLine + $feature.ADDRESS_1 + TextFormatting.NewLine + $feature.ADDRESS_2
    Python
    "Name: " + [NAME] + '\n' + [ADDRESS_1] + '\n' + [ADDRESS_2]
    VBScript
    "Name: " & [NAME] & vbCrLf& [ADDRESS_1] & vbCrLf& [ADDRESS_2]
    JScript
    "Name: " + [NAME] + "\r" + [ADDRESS_1] + "\r" + [ADDRESS_2]
  • Create stacked text based on text from one field; for example, this 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 your labels; for example, this 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);
}
  • Use only part of the field as the label; for example, this 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;
}
  • 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 and 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.

The following are additional resources:

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

(Some information is housed on web pages not created, owned, or maintained by Esri. Esri cannot guarantee the availability of these pages and is not responsible for the content found on them.)

Feedback on this topic?

In this topic
  1. Label expressions
  2. Writing a label expression
  3. Expression examples