LabelClass

AMD: require(["esri/layers/support/LabelClass"], (LabelClass) => { /* code goes here */ });
ESM: import LabelClass from "@arcgis/core/layers/support/LabelClass";
Class: esri/layers/support/LabelClass
Inheritance: LabelClass Accessor
Since: ArcGIS API for JavaScript 4.0

Defines label expressions, symbols, scale ranges, label priorities, and label placement options for labels on a layer. See the Labeling guide for more information about labeling.

Known Limitations

See also:
Example:
const labelClass = {  // autocasts as new LabelClass()
  symbol: {
    type: "text",  // autocasts as new TextSymbol()
    color: "white",
    haloColor: "blue",
    haloSize: 1,
    font: {  // autocast as new Font()
       family: "Ubuntu Mono",
       size: 14,
       weight: "bold"
     }
  },
  labelPlacement: "above-right",
  labelExpressionInfo: {
    expression: "$feature.Team + TextFormatting.NewLine + $feature.Division"
  },
  maxScale: 0,
  minScale: 25000000,
  where: "Conference = 'AFC'"
};

const labelLayer = new FeatureLayer({
  portalItem: {  // autocasts as new PortalItem()
    id: "7f0bfc7bf67a407d8efebf584f6d956d"
  },
  labelingInfo: [labelClass]
});

Constructors

new LabelClass(properties)
Parameter:
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
Show inherited properties Hide inherited properties
Name Type Summary Class
Stringmore details

The name of the class.

more detailsAccessor
Stringmore details

Defines how labels should be placed relative to one another.

more detailsLabelClass
Stringmore details

Defines the content of label text for MapImageLayer.

more detailsLabelClass
Objectmore details

Defines the content of label text for FeatureLayer.

more detailsLabelClass
Stringmore details

The position of the label.

more detailsLabelClass
Numbermore details

The maximum scale (most zoomed in) at which labels are visible in the view.

more detailsLabelClass
Numbermore details

The minimum scale (most zoomed out) at which labels are visible in the view.

more detailsLabelClass
TextSymbol|LabelSymbol3Dmore details

Defines the symbol used for rendering the label.

more detailsLabelClass
Booleanmore details

Indicates whether to use domain names if the fields in the labelExpression or labelExpressionInfo have domains.

more detailsLabelClass
Stringmore details

A SQL where clause used to determine the features to which the label class should be applied.

more detailsLabelClass

Property Details

declaredClass Stringreadonly inherited
Since: ArcGIS API for JavaScript 4.7

The name of the class. The declared class name is formatted as esri.folder.className.

deconflictionStrategy String
Since: ArcGIS API for JavaScript 4.16

Defines how labels should be placed relative to one another. By default, labels have a static deconfliction strategy, meaning labels that overlap are dropped to make them easier to read.

In some cases where few labels overlap, it may be preferable to turn off label deconfliction with the none option. It is also advisable to turn off deconfliction when labeling clusters with a count of features in the center of the cluster.

The following images illustrate when you may, or may not, want labels to deconflict.

When labeling dense layers, the default deconfliction strategy (static) is preferable since labeling all features causes significant overlap, making the labels illegible. Keeping the default setting allows some labels to render. As the user zooms in, all labels will eventually come into view.

static (default) none
layer-deconfliction-on layer-deconfliction-off

When labeling clusters (or even sparsely distributed features) with small labels, it may be preferable to allow labels to slightly overlap since the information is still legible and doesn't significantly occlude the visualization. In the clustering scenario, a label deconfliction setting of static may actually cause more confusion, making some features not appear to be clusters.

static (default) none
cluster-deconfliction-on cluster-deconfliction-off

Known Limitations

Currently, this property only applies to FeatureLayer, CSVLayer, and StreamLayer in 2D MapViews.

Possible Values:"none"|"static"

Default Value:static
Example:
// Ensures all labels are displayed regardless
// of whether they overlap
labelClass.deconflictionStrategy = "none";
labelExpression String

Defines the content of label text for MapImageLayer. If working with FeatureLayer, use labelExpressionInfo instead.

Attribute values may be included in labels using SQL syntax. To include an attribute value in a label, wrap the name of the field in square brackets []. See the example snippet below.

Default Value:null
Example:
// For Spokane County, WA, label will display: "Spokane County, Washington"
labelClass.labelExpression = '[COUNTY_NAME] CONCAT " County, " CONCAT [STATE_NAME]';
labelExpressionInfo Object

Defines the content of label text for FeatureLayer. If working with MapImageLayer, use labelExpression instead.

Properties:
value String
Deprecated since version 4.5. Use expression instead.
optional

The SQL expression defining the content of the label text.

expression String

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, the following expression appends city to the end of the label if the feature's population field contains a number greater than 10,000. Otherwise, town is appended to the end of the label. Additionally, you can use TextFormatting.NewLine to add a new line to the label.

IIF($feature.POPULATION > 10000, $feature.NAME + ' city', $feature.NAME + ' town')

title String
optional

The title of the label expression. This is particularly useful in the case of multiple label classes.

Default Value:null
Example:
// For Spokane County, WA, label will display: "Spokane County, Washington"
labelClass.labelExpressionInfo = {
  expression: "$feature.COUNTY_NAME + ' County, ' + $feature.STATE_NAME"
};
labelPlacement String

The position of the label. Possible values are based on the feature type. This property requires a value.

Feature Type Possible Values
Points above-center, above-left, above-right, below-center, below-left, below-right, center-center, center-left, center-right
Polylines 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
Polygons always-horizontal

Known Limitations

  • Currently, if the label has a line callout in a 3D SceneView, then only above-center is supported.
  • Label placement only applies to Point layers in 3D SceneViews.
  • FeatureLayer Polylines only support center-along label placement in 2D MapViews.

Possible Values:"above-center"|"above-left"|"above-right"|"below-center"|"below-left"|"below-right"|"center-center"|"center-left"|"center-right"|"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"|"always-horizontal"

Default Value:null
See also:
Example:
labelClass.labelPlacement = "above-right";
maxScale Number

The maximum scale (most zoomed in) at which labels are visible in the view. A value of 0 means the label's visibility does not have a maximum scale. The maxScale value should always be smaller than the minScale value, and greater than or equal to the service specification.

Default Value:0
minScale Number

The minimum scale (most zoomed out) at which labels are visible in the view. A value of 0 means the label's visibility does not have a minimum scale. The minScale value should always be larger than the maxScale value, and lesser than or equal to the service specification.

Default Value:0

Defines the symbol used for rendering the label. If not set, the default symbol will be used. See the example below.

Example:
// If not set, this default symbol will be used
labelClass.symbol = {
  type: "text",
  color: [255, 255, 255, 255],  // white
  font: { family: "Arial Unicode MS", size: 10, weight: "bold" },
  haloColor: [0, 0, 0, 255],  // black
  haloSize: 1
};
useCodedValues Boolean

Indicates whether to use domain names if the fields in the labelExpression or labelExpressionInfo have domains.

where String

A SQL where clause used to determine the features to which the label class should be applied. When specified, only features evaluating to true based on this expression will be labeled.

Default Value:null
Examples:
labelClass.where = "CITYNAME = 'Redlands'";
labelClass.where = "MARKER_ACTIVITY IN ('Picnicking', 'Group Camping')";

Method Overview

Name Return Type Summary Class
LabelClassmore details

Creates a deep clone of the LabelClass.

more detailsLabelClass
*more details

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product.

more detailsLabelClass
Objectmore details

Converts an instance of this class to its ArcGIS portal JSON representation.

more detailsLabelClass

Method Details

clone(){LabelClass}

Creates a deep clone of the LabelClass.

Returns:
Type Description
LabelClass A deep clone of the object that invoked this method.
Example:
// Creates a deep clone of the layer's first labelClass
let label = layer.labelingInfo[0].clone();
fromJSON(json){*}static

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product. The object passed into the input json parameter often comes from a response to a query operation in the REST API or a toJSON() method from another ArcGIS product. See the Using fromJSON() topic in the Guide for details and examples of when and how to use this function.

Parameter:
json Object

A JSON representation of the instance in the ArcGIS format. See the ArcGIS REST API documentation for examples of the structure of various input JSON objects.

Returns:
Type Description
* Returns a new instance of this class.
toJSON(){Object}

Converts an instance of this class to its ArcGIS portal JSON representation. See the Using fromJSON() guide topic for more information.

Returns:
Type Description
Object The ArcGIS portal JSON representation of an instance of this class.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.