Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: LabelClass

require(["esri/layers/LabelClass"], function(LabelClass) { /* code goes here */ });

Description

(Added at v3.6)
Use label classes to restrict labels to certain features or to specify different label fields, symbols, scale ranges, label priorities, and sets of label placement options for different groups of labels.

Samples

Search for samples that use this class.

Constructors

NameSummary
new LabelClass(json?)Creates a label class, used for formatting parameters, symbols, date, etc.

Properties

NameTypeSummary
fieldInfosObject[]An array of objects representing field information to label.
labelExpressionStringAdjusts the formatting of labels.
labelExpressionInfoObjectUse this property when working with FeatureLayer layer types.
labelPlacementStringThe position of the label.
maxScaleNumberThe maximum scale to show labels.
minScaleNumberThe minimum scale to show labels.
sizeInfoObjectIf this is defined, the symbol size changes proportionally.
symbolTextSymbolSets the Rendering symbol for the label.
useCodedValuesBooleanWhen true, show the fields in the labelExpression that have domains using the domain's name.
whereStringA where clause determining which features are labeled.
Constructor Details

new LabelClass(json?)

Creates a label class, used for formatting parameters, symbols, date, etc.
Parameters:
<Object> json Optional Various options to configure this LabelClass. Any property can be passed into this object.
Sample:

//make sure the Map's showLabels option is set to true
  var map = new Map("map", {
    basemap: "streets",
    center:[-80, 30],
    zoom: 5,
    showLabels : true
  });
 
//create featurelayer
  var flayer = new FeatureLayer(url, {
    outFields: ["*"] //make sure field to label is specified here in outFields
  });


//create a text symbol and renderer to define the style of labels
   var labelSymbol = new TextSymbol(); 

var json = {
  "labelExpressionInfo": {"value": "{LocalTime}"},
  "useCodedValues": false,
  "labelPlacement":"above-right",
  "fieldInfos": [{fieldName: "LocalTime",format: { "dateFormat": "shortDate"}}]
  };

//create instance of LabelClass
  var lc = new LabelClass(json);
  lc.symbol = labelSymbol; // symbol also can be set in LabelClass' json
  flayer.setLabelingInfo([ lc ]);
    
Property Details

<Object[]> fieldInfos

An array of objects representing field information to label. This is used for formatting Date/Time and Number. It is not necessary if working with string types. See the fieldInfos specifications table below for additional information. (Added at v3.14)
Object Specifications:
<fieldInfos>
<String> fieldName Optional The name of the field to label. This should only be used when working with Date/Time and Number field types.
<Object> format Optional This object can be used with numerical or date fields to provide more detail about how values should be displayed in labels. NOTE: Only applies to date or number fields, (for example float, double, integer). The format object contains the following properties:
  • dateFormat: A string used with date fields to specify how the date should appear in labels. Acceptable values can be found in this help topic.
  • digitSeparator: Used with the places property below. It is a boolean used with numerical fields. A value of true allows the number to have a digit (or thousands) separator when the value appears in labels. Depending on the locale, this separator is a decimal point or a comma. A value of false means that no separator will be used.
  • places: Used with the digitSeparator property above. An integer used with numerical fields to specify the number of supported decimal places that should appear in labels. Any places beyond this value are rounded.
Sample snippet showing various formats.
"fieldInfos": [
  { fieldName: "created_date", 
    format: { dateFormat: "shortDate"}
  }, 
  { 
    fieldName: "last_edited_date", 
    format: { dateFormat: "longDate"} 
  }, 
  { 
    fieldName: "eventtype", 
    format: { places: 6, digitSeparator: true } 
  } 
]
Sample:
 "fieldInfos": [{
   fieldName: "LocalTime",
   format:{"dateFormat": "shortDate"}
   }
 ]

<String> labelExpression

Adjusts the formatting of labels. See the Labeling Objects section of the ArcGIS REST API documentation for available options.

NOTE: Currently labelExpression is not supported with FeatureLayer types, please use labelExpressionInfo instead. This supports using a combination of attribute fields and simple text.

If working with ArcGISDynamicMapServiceLayer layers, please continue to use labelExpression.
Sample:
"Name: {CITY_NAME} Area: {CITY_AREA}"

<Object> labelExpressionInfo

Use this property when working with FeatureLayer layer types. See the object specification table for labelExpressionInfo below for more details. If working with ArcGISDynamicMapServiceLayer layers, use labelExpression since labelExpressionInfo is not supported. (Added at v3.12)
Object Specifications:
<labelExpressionInfo>
<String> expression Required An Arcade expression that evaluates to a string used to label features in the layer. The most simple expressions return field values. For example, to label a layer of cities with their names, simply reference the field value with the global variable: "$feature.CITY_NAME". Expressions can be more sophisticated and use logical functions. This may be useful if you want to use classed labels. For example, "IIF($feature.POPULATION > 10000, $feature.NAME + ' city', $feature.NAME + ' town')".
<String> value Optional Deprecated at v3.19. Use the expression property instead. The text used to label the feature. Field values may be referenced using the following syntax: "{FIELD_NAME}". For example, to label points representing city's with their name and population in parentheses, you would use the following string: labelExpressionInfo.value = "{CITY_NAME} ({POP_2012})"
Sample:
//This property should be used instead as it provides more options when labeling text, (only supported with feature layers)
  labelExpressionInfo: { 
    expression: "City of $feature.CITY_NAME has population $feature.POPULATION"
  }

<String> labelPlacement

The position of the label. Available values for various feature types:
  • Point: "above-center", "above-left", "above-right", "below-center", "below-left", "below-right", "center-center", "center-left", "center-right"
  • Polyline/Line: "above-after", "above-along", "above-before", "above-start", "above-end", "below-after", "below-along", "below-before", "below-start", "below-end", "center-after", "center-along", "center-before", "center-start", "center-end"
  • Polygon: "always-horizontal"

<Number> maxScale

The maximum scale to show labels. Note: the number of maxScale should always be less than the number of minScale.

<Number> minScale

The minimum scale to show labels. Note: the number of minScale should always be greater than the number of maxScale.

<Object> sizeInfo

If this is defined, the symbol size changes proportionally. See the object specifications table below for a list of its available properties. (Added at v3.11)
Object Specifications:
<sizeInfo>
<String> field Required Required name of the feature attribute field that contains the data value.
<Number> maxDataValue Required The maximum data value.
<Number> maxSize Required Maximum symbol size (in pixels).
<Number> minDataValue Required The minimum data value.
<Number> minSize Required The symbol size (in pixels) to use for a feature for a minimum data value.
Sample:
var sizeInfo = {
   "field": "POP_RANK",
   "minSize": 10,
   "maxSize": 20,
   "minDataValue": 1,
   "maxDataValue": 7
};

<TextSymbol> symbol

Sets the Rendering symbol for the label.
Sample:
require([
  "esri/layers/LabelClass", "esri/symbols/TextSymbol", "esri/symbols/Font", "esri/Color", ... 
], function(LabelClass, TextSymbol, Font, Color){
  var labelClass = new LabelClass();
  labelClass.symbol = new TextSymbol({
    font: new Font("12", Font.STYLE_NORMAL, Font.VARIANT_NORMAL, Font.WEIGHT_BOLD, "Helvetica"),
    color: new Color("#666633")
  });
});

<Boolean> useCodedValues

When true, show the fields in the labelExpression that have domains using the domain's name.
Known values: true | false

<String> where

A where clause determining which features are labeled. When specified, only features that match this clause will be labeled. Any legal SQL where clause operating on the fields in the layer is allowed.
Sample:
labelClass.where = "areaname='Redlands'"