Labeling features client-side | Guide | ArcGIS API for JavaScript 3.26

Implementation

This tutorial walks through the code used in the Labeling features on the client sample. It works directly with a FeatureLayer class' labelingInfo. In order to access this, set the Map's showLabels constructor option to true. Once done, any FeatureLayer added to the map will automatically label based on its labelingInfo. Use the LabelClass if needing to modify any of these labeling properties.

Boilerplate

Let's start with a page that has a map with a single feature layer. Take special note of the showLabels constructor option. This must be set to true for all of the labels to be placed correctly. The code below also overrides the default symbology for the states layer by creating a SimpleRenderer:

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
    <title></title>
    <link rel="stylesheet" href="https://js.arcgis.com/3.26/esri/css/esri.css">
    <style>
      html, body, #map {
        height: 100%; width: 100%; margin: 0; padding: 0; 
      }
    </style>

    <script src="https://js.arcgis.com/3.26/"></script>
    <script>
      var map;
    
      require([
        "esri/map", 
        "esri/geometry/Extent",
        "esri/layers/FeatureLayer",
        "esri/symbols/SimpleLineSymbol",
        "esri/symbols/SimpleFillSymbol",
        "esri/symbols/TextSymbol",
        "esri/renderers/SimpleRenderer",
        "dojo/_base/Color",
        "dojo/domReady!"
      ], function(Map, Extent, FeatureLayer, SimpleLineSymbol, SimpleFillSymbol,
        TextSymbol, SimpleRenderer, Color) {
        // load the map centered on the United States
        var bbox = new Extent({"xmin":-1940058,"ymin":-814715,"xmax":1683105,"ymax":1446096,"spatialReference":{"wkid":102003}});
        map = new Map("map", {
          extent: bbox,
          showLabels : true //very important that this must be set to true!   
        });

        var labelField = "STATE_NAME";

        // create a renderer for the states layer to override default symbology
        var statesColor = new Color("#666");
        var statesLine = new SimpleLineSymbol("solid", statesColor, 1.5);
        var statesSymbol = new SimpleFillSymbol("solid", statesLine, null);
        var statesRenderer = new SimpleRenderer(statesSymbol);
        // create a feature layer to show country boundaries
        var statesUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";
        var states = new FeatureLayer(statesUrl, {
          id: "states",
          outFields: ["*"]
        });
        states.setRenderer(statesRenderer);
        map.addLayer(states);
      });
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>

Load the LabelClass module

The module identifier for the LabelClass is esri/layers/LabelClass and the preferred argument alias is LabelClass. Add the module ID to the dependency list and the argument alias to the require callback. Here's what the entire require() looks like:

require([
  "esri/map",
  "esri/geometry/Extent",
  "esri/layers/FeatureLayer",
  "esri/symbols/SimpleLineSymbol",
  "esri/symbols/SimpleFillSymbol",
  "esri/symbols/TextSymbol",
  "esri/renderers/SimpleRenderer",
  "esri/layers/LabelClass",
  "dojo/_base/Color",
  "dojo/domReady!"
], function(Map, Extent, FeatureLayer, SimpleLineSymbol, SimpleFillSymbol,
  TextSymbol, SimpleRenderer, LabelClass, Color) {

Label a feature layer

After the code that creates a map, add the code below to create a text symbol to be used for state labels, use the text symbol as the basis for LabelClass.symbol in step 5 below.
```
// create a text symbol to define the style of labels
var statesLabel = new TextSymbol().setColor(statesColor);
statesLabel.font.setSize("14pt");
statesLabel.font.setFamily("arial");
```

Create the LabelClass

After creating the text symbol. You need to create a LabelClass. Here is where you specify all the properties defining the labeling of the feature layer. You will first create a JSON object containing any properties you wish to pass in when creating this LabelClass instance. Although the text symbol created is applied to this class, it could also be set directly within the JSON itself.

//Create a JSON object which contains the labeling properties. At the very least, specify which field to label using the labelExpressionInfo property. Other properties can also be specified such as whether to work with coded value domains, fieldinfos (if working with dates or number formatted fields, and even symbology if not specified as above)
var json = {
  "labelExpressionInfo": {"value": "{STATE_NAME}"}
};
//create instance of LabelClass (note: multiple LabelClasses can also be passed in as an array)
var labelClass = new LabelClass(json);
labelClass.symbol = statesLabel; // symbol also can be set in LabelClass' json

Apply the labelingInfo to the States feature layer and add to the map

Lastly, you need to set the featurelayer's setLabelingInfo method using the LabelClass you created above. After this is set, add the layer to the map. You should now see the States feature layer rendered in addition to the labeling specified above.
```
states.setLabelingInfo([ labelClass ]);
map.addLayer(states);
```

	Site wide shortcuts
`?`	Bring up this help dialog
`esc`	Dismiss this help dialog
`gh`	Go to Home
`gg`	Go to Guide
`ga`	Go to API Reference
`gs`	Go to Sample Code
`gt`	Scroll to top of page
`spacebar`	Scroll page down
`shift spacebar`	Scroll page up
`gb`	Scroll to bottom of page

Implementation

Boilerplate

Load the LabelClass module

Label a feature layer

Create the LabelClass

Apply the labelingInfo to the States feature layer and add to the map

Keyboard shortcuts