Hide Table of Contents
Labeling features client-side

This tutorial covers the following:

  1. Implementation
  2. Boilerplate
  3. Load the LabelClass module
  4. Label a feature layer
  5. Create the LabelClass
  6. Apply the labelingInfo to the States feature layer and add to the map
  1. 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.

  2. 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.22/esri/css/esri.css">
        <style>
          html, body, #map {
            height: 100%; width: 100%; margin: 0; padding: 0; 
          }
        </style>
    
        <script src="https://js.arcgis.com/3.22/"></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>
    
  3. 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) {
    
  4. 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");
    
  5. 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
    
  6. 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);