Labeling

Labels help identify features, establish a visual hierarchy of important features, and focus the user's attention on the map's purpose. Label options and capabilities (such as label placement and available fonts) vary depending on the layer type, geometry type, and view type (2D or 3D).

This guide page will demonstrate the possible labeling scenarios based on those different properties and fonts. The FAQ at the bottom contains information about useful workflows and answers to common questions. Additionally, this guide page will explore labeling adjacent use cases, such as text in TextSymbol and TextSymbol3DLayer, for text symbol previews using symbolUtils.renderPreviewHTML, and print considerations.

2D MapView labeling

Labeling is supported for FeatureLayer, CSVLayer, GeoJSONLayer, StreamLayer, OGCFeatureLayer, and WFSLayer in 2D MapViews. The labelingInfo property is specified as an array of LabelClass objects, which contains labelExpressionInfo, labelPlacement, and TextSymbol. The TextSymbol class supports altering the label graphic's color, font, halo, and other properties. Labeling is supported for Points, Polylines, and Polygons.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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: "Noto Sans",
       size: 14
     }
  },
  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]
});

Sample: Multi-line labels

3D SceneView labeling

Labeling is supported for all layer types with a labelingInfo property, such as FeatureLayer and SceneLayer. This property is specified as an array of LabelClass objects, which contains the labelExpressionInfo, labelPlacement, and TextSymbol3DLayer. The TextSymbol3DLayer class supports altering the label graphic's material, font, halo, and other properties.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
const labelClass = {  // autocasts as new LabelClass()
  symbol: {
    type: "label-3d", // autocasts as new LabelSymbol3D()
    symbolLayers: [
      {
        type: "text", // autocasts as new TextSymbol3DLayer()
        material: {
          color: "purple"
        },
        font: {  // autocasts as new Font()
          family: "Just Another Hand",
          weight: bold
        },
        size: 22
      }
    ]
  },
  labelPlacement: "below-center",
  labelExpressionInfo: {
    expression: 'DefaultValue($feature.CITY_NAME, "no data")'
  }
};

const labelLayer = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/CITIES_EastUSA/FeatureServer/0",
  labelingInfo: [labelClass]
});

Known Limitations (SceneView)

Sample: Flat vs. volumetric 3D symbol layers

Fonts

Typically, you won't need to be concerned with where the font files are hosted or which file types are used. However, if you are working with custom fonts or in a disconnected environment, it is worth reading this entire section. There are different types of font files used for labeling that are accessible from different locations, depending on the class, layer type, and if you are working in 2D or 3D. There are multiple ways that fonts can be consumed:

  • From https://static.arcgis.com/fonts in pbf format
  • From https://static.arcgis.com/fonts/woff2 in woff2 format
  • Referenced from a server in pbf, otf, ttf, woff, or woff2 format
  • From the fonts available on the user's computer and web browser

MapImageLayer fonts

MapImageLayer fonts come from a web browser or the user's computer.

Labeling is supported for MapImageLayer by setting the labelingInfo property on the Sublayer class. The labelingInfo property is specified as an array of LabelClass objects, containing the labelExpression, labelPlacement, and TextSymbol. The TextSymbol class supports altering the label graphic's color, font, halo, and other properties. Labeling is supported for Points, Polylines, and Polygons.

The supported font families for MapImageLayers in a MapView depend on the fonts installed on the ArcGIS Server that published the layer. This is the same for 2D MapViews and 3D SceneViews. To check what fonts are available on ArcGIS Server, run the Available Fonts task under Home > services > System > PublishingTools (GPServer) (requires admin access). To add a new font, the font must be installed on your computer and accessible to ArcGIS Server by registering it using ArcGIS Desktop. If an app uses a font that is not installed, the Font class implements a fallback mechanism that will use the default font family value, which is sans-serif.

Sample: MapImageLayer - label sublayer features

Non-MapImageLayer fonts

Support for Font.family, Font.style, and Font.weight properties are based on the fonts files. We host many fonts on https://static.arcgis.com/fonts that can be easily accessed for labeling.

If a Font is unavailable, it will use the default font family, sans-serif. This uses the Arial Unicode MS font file. Fonts with bold and/or italic require these properties to be set in the Font.style and Font.weight properties, as opposed to being set in the Font.family. To see which fonts support what types of characters (e.g. Latin, Cyrillic, CJKV), you can search for the font name in the Microsoft Typography or Google Fonts.

Non-MapImageLayer layers that can be labeled:
CSVLayer, FeatureLayer, GeoJSONLayer, OGCFeatureLayer, StreamLayer, WFSLayer.

List of fonts currently hosted on https://static.arcgis.com/fonts in pbf and woff2 formats (currently Palatino Linotype Regular, Arial Regular, Arial Bold, Arial Bold Italic, and Arial Italic are only available in pbf):

FontPreviewCode
Abril Fatface RegularAbril Fatface RegularCopy
Alegreya BoldAlegreya BoldCopy
Alegreya Bold ItalicAlegreya Bold ItalicCopy
Alegreya ItalicAlegreya ItalicCopy
Alegreya RegularAlegreya RegularCopy
Alegreya SC BoldAlegreya SC BoldCopy
Alegreya SC ItalicAlegreya SC ItalicCopy
Alegreya SC RegularAlegreya SC RegularCopy
Alegreya Sans ItalicAlegreya Sans ItalicCopy
Amarante RegularAmarante RegularCopy
Amatic SC BoldAmatic SC BoldCopy
Arial BoldArial BoldCopy
Arial Bold ItalicArial Bold ItalicCopy
Arial ItalicArial ItalicCopy
Arial RegularArial RegularCopy
Arial Unicode MS BoldArial Unicode MS BoldCopy
Arial Unicode MS RegularArial Unicode MS RegularCopy
Atomic Age RegularAtomic Age RegularCopy
Audiowide RegularAudiowide RegularCopy
Avenir Next LT Pro BoldAvenir Next LT Pro BoldCopy
Avenir Next LT Pro Bold ItalicAvenir Next LT Pro Bold ItalicCopy
Avenir Next LT Pro Demi ItalicAvenir Next LT Pro Demi ItalicCopy
Avenir Next LT Pro ItalicAvenir Next LT Pro ItalicCopy
Avenir Next LT Pro LightAvenir Next LT Pro LightCopy
Avenir Next LT Pro Light ItalicAvenir Next LT Pro Light ItalicCopy
Avenir Next LT Pro Medium BoldAvenir Next LT Pro Medium BoldCopy
Avenir Next LT Pro Medium Bold ItalicAvenir Next LT Pro Medium Bold ItalicCopy
Avenir Next LT Pro RegularAvenir Next LT Pro RegularCopy
Avenir Next LT Pro Regular BoldAvenir Next LT Pro Regular BoldCopy
BellTopo Sans BoldBellTopo Sans BoldCopy
BellTopo Sans Bold ItalicBellTopo Sans Bold ItalicCopy
BellTopo Sans ItalicBellTopo Sans ItalicCopy
BellTopo Sans RegularBellTopo Sans RegularCopy
Belleza RegularBelleza RegularCopy
Black Ops One RegularBlack Ops One RegularCopy
Cabin Sketch BoldCabin Sketch BoldCopy
Cabin Sketch RegularCabin Sketch RegularCopy
Coming Soon RegularComing Soon RegularCopy
FGDC GeoAge RegularFGDC GeoAge RegularCopy
Homemade Apple RegularHomemade Apple RegularCopy
IM FELL DW Pica PRO ItalicIM FELL DW Pica PRO ItalicCopy
IM FELL DW Pica PRO RegularIM FELL DW Pica PRO RegularCopy
Josefin Sans RegularJosefin Sans RegularCopy
Josefin Sans Semibold ItalicJosefin Sans Semibold ItalicCopy
Josefin Slab BoldJosefin Slab BoldCopy
Josefin Slab Bold ItalicJosefin Slab Bold ItalicCopy
Josefin Slab ItalicJosefin Slab ItalicCopy
Josefin Slab Light ItalicJosefin Slab Light ItalicCopy
Josefin Slab RegularJosefin Slab RegularCopy
Josefin Slab Thin ItalicJosefin Slab Thin ItalicCopy
Just Another Hand RegularJust Another Hand RegularCopy
Kranky RegularKranky RegularCopy
Life Savers BoldLife Savers BoldCopy
Loved by the King RegularLoved by the King RegularCopy
Merriweather BoldMerriweather BoldCopy
Merriweather Bold ItalicMerriweather Bold ItalicCopy
Merriweather ItalicMerriweather ItalicCopy
Merriweather RegularMerriweather RegularCopy
Montserrat BoldMontserrat BoldCopy
Montserrat ItalicMontserrat ItalicCopy
Montserrat Medium ItalicMontserrat Medium ItalicCopy
Montserrat RegularMontserrat RegularCopy
Montserrat Semibold ItalicMontserrat Semibold ItalicCopy
Noto Sans BoldNoto Sans BoldCopy
Noto Sans Bold ItalicNoto Sans Bold ItalicCopy
Noto Sans ItalicNoto Sans ItalicCopy
Noto Sans RegularNoto Sans RegularCopy
Noto Serif BoldNoto Serif BoldCopy
Noto Serif Bold ItalicNoto Serif Bold ItalicCopy
Noto Serif ItalicNoto Serif ItalicCopy
Noto Serif RegularNoto Serif RegularCopy
Old Standard TT BoldOld Standard TT BoldCopy
Old Standard TT ItalicOld Standard TT ItalicCopy
Old Standard TT RegularOld Standard TT RegularCopy
Orbitron BoldOrbitron BoldCopy
Orbitron RegularOrbitron RegularCopy
Oregano ItalicOregano ItalicCopy
Oregano RegularOregano RegularCopy
Oswald BoldOswald BoldCopy
Oswald RegularOswald RegularCopy
Pacifico RegularPacifico RegularCopy
Palatino Linotype RegularPalatino Linotype RegularCopy
Playfair Display BlackPlayfair Display BlackCopy
Playfair Display BoldPlayfair Display BoldCopy
Playfair Display Bold ItalicPlayfair Display Bold ItalicCopy
Playfair Display ItalicPlayfair Display ItalicCopy
Playfair Display RegularPlayfair Display RegularCopy
Playfair Display SC BoldPlayfair Display SC BoldCopy
Playfair Display SC RegularPlayfair Display SC RegularCopy
Redressed RegularRedressed RegularCopy
Risque RegularRisque RegularCopy
Roboto BoldRoboto BoldCopy
Roboto Bold ItalicRoboto Bold ItalicCopy
Roboto Condensed ItalicRoboto Condensed ItalicCopy
Roboto Condensed Light ItalicRoboto Condensed Light ItalicCopy
Roboto ItalicRoboto ItalicCopy
Roboto RegularRoboto RegularCopy
Rye RegularRye RegularCopy
Special Elite RegularSpecial Elite RegularCopy
Syncopate BoldSyncopate BoldCopy
Syncopate RegularSyncopate RegularCopy
Tangerine RegularTangerine RegularCopy
Ubuntu BoldUbuntu BoldCopy
Ubuntu Bold ItalicUbuntu Bold ItalicCopy
Ubuntu Condensed RegularUbuntu Condensed RegularCopy
Ubuntu ItalicUbuntu ItalicCopy
Ubuntu LightUbuntu LightCopy
Ubuntu Light BoldUbuntu Light BoldCopy
Ubuntu Light Bold ItalicUbuntu Light Bold ItalicCopy
Ubuntu Light ItalicUbuntu Light ItalicCopy
Ubuntu Medium ItalicUbuntu Medium ItalicCopy
Ubuntu Mono BoldUbuntu Mono BoldCopy
Ubuntu Mono Bold ItalicUbuntu Mono Bold ItalicCopy
Ubuntu Mono ItalicUbuntu Mono ItalicCopy
Ubuntu Mono RegularUbuntu Mono RegularCopy
Ubuntu RegularUbuntu RegularCopy
UnifrakturCook BoldUnifrakturCook BoldCopy
Vast Shadow RegularVast Shadow RegularCopy
Walter Turncoat RegularWalter Turncoat RegularCopy
Preview:
Code:
Use dark colors for code blocksCopy
1
{}

SceneView fonts

The supported font families for 3D SceneViews are dependent upon (in order of precedence): the fonts installed on the user's computer and web browser, and then the fonts available on https://static.arcgis.com/fonts/woff2 or referenced from a server. If an app uses a font not installed on the user's computer and web browser, the app will search our hosted fonts. If a Font is unavailable there, the Font class implements a fallback mechanism that will use the default font family value, sans-serif. See these references for instructions on how to install a new font on Windows or Mac.

Note that these fonts also apply to TextSymbol3DLayer, whether it's used as graphics or labels in a 3D SceneView.

Fonts that are not installed locally can also be loaded from a url by defining a @font-face in a css file:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
@font-face {
   font-family: "MyFont";
   font-style: normal;
   font-weight: 400;
   font-display: auto;
   src: url("./my-font.ttf") format("truetype");
}

And referencing it from the Font.family property in a symbol layer:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
const labelSymbol = {
  type: "label-3d", // autocasts as new LabelSymbol3D
  symbolLayers: [
    {
      type: "text", // autocasts as new TextSymbol3DLayer()
      material: {
        color: [0, 0, 0, 0.8]
      },
      font: {
        size: 30,
        family: "MyFont"
      }
    }
  ]
}

Fonts can also be referenced from https://static.arcgis.com/fonts/woff2 by default:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
const labelClass = {  // autocasts as new LabelClass()
  symbol: {
    type: "label-3d", // autocasts as new LabelSymbol3D()
    symbolLayers: [
      {
        type: "text", // autocasts as new TextSymbol3DLayer()
        material: {
          color: "black"
        },
        halo: {
          color: [255, 255, 255, 0.7],
          size: 2
        },
        font: {
          family: "Noto Sans"
        },
        size: 10
      }
    ]
  },
  labelPlacement: "above-right",
  labelExpressionInfo: {
    expression: `$feature.NAME + TextFormatting.NewLine + Text($feature.HOEHE, "#,### m")`
  }
};

const labelLayer = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/AlpineSummits/FeatureServer/0",
  elevationInfo: {
    mode: "relative-to-ground"
  },
  labelingInfo: [labelClass]
});

Custom fonts and disconnected environments

In 2D MapViews, the fonts files used are pbf for all non-MapImageLayer layers and for TextSymbol, and woff2 for renderPreviewHTML.

In 3D SceneViews, the fonts files used are ttf, otf, woff, or woff2 format for all non-MapImageLayer layers and for TextSymbol3DLayer, and woff2 for renderPreviewHTML. Also, for 3D SceneViews, font files from https://static.arcgis.com/fonts are only consumed in woff2 format.

By default, the fonts available are mostly the same ones used by the Esri Vector Basemaps. These fonts are listed in the Esri Vector Basemap Reference Document, under the Esri Vector Basemaps Resources\Fonts heading. These fonts are available via https://static.arcgis.com/fonts. Access to that URL is required for the app to render labels. If this URL is not accessible (e.g. disconnected or offline environment), or a font is being used that is not hosted there, then the fontsUrl can be configured to point to your own font files by setting the esriConfig.fontsUrl property. These font files must be the correct file type to display. Reference the table below to see the required types of font files based on the class and if you are working in 2D or 3D.

ViewApplied toFont source
2D & 3DMapImageLayerUser's computer and web browser (ttf, otf, woff, or woff2 format)
2D & 3DrenderPreviewHTMLhttps://static.arcgis.com/fonts/woff2 (woff2 format)
hosted on a server (woff2 format)
2D MapViewNon-MapImageLayerhttps://static.arcgis.com/fonts (pbf format)
hosted on a server (pbf format)
3D SceneViewNon-MapImageLayerUser's computer and web browser
https://static.arcgis.com/fonts/woff2 (woff2 format)
referenced from a server (ttf, otf, woff, or woff2 format)
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
esriConfig.fontsUrl = "https://myserver.com/fonts";  // reference fonts from a server in `pbf`

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: "Wes Welker",
       size: 83
     }
  },
  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]
});

Alternative labeling scenarios

Additionally, this guide page will explore labeling adjacent use cases. The labeling workflow doesn't end with labeling layers. There are other ways to label features, as well as other app considerations for those labeled features.

TextSymbol and TextSymbol3DLayer

TextSymbol and TextSymbol3DLayer are both part of the typical labeling workflow, and can also be used in an alternative labeling experience. These symbols can be used as individual labels themselves, with the label's font and text representing the visualization.

Here is an example of a TextSymbol being added to 2D MapView with formatted text:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
const textSymbol = {
  type: "text",  // autocasts as new TextSymbol()
  color: "blue",
  haloColor: "red",
  haloSize: "1px",
  text: "Wish you were here",
  xoffset: 3,
  yoffset: 3,
  font: {  // autocasts as new Font()
    size: 12,
    family: "Orbitron",
    weight: "bold"
  }
};

const point = {
  type: "point",  // autocasts as new Point()
  longitude: -71.26,
  latitude:  42.09
};

const pointGraphic = new Graphic({
  geometry: point,
  symbol: textSymbol
});

view.graphics.add(pointGraphic);

Here is an example of a TextSymbol3DLayer being added to a 3D SceneView with formatted text:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
const textSymbol3D = {
  type: "point-3d",  // autocasts as new PointSymbol3D()
  symbolLayers: [{
    type: "text",  // autocasts as new TextSymbol3DLayer()
    font: {  // autocasts as new Font()
      size: 12,
      family: "Just Another Hand"
    },
    text: "Wish I was here",
    material: {
      color: "green"
    },
    size: 12
  }]
};

const point = {
  type: "point",  // autocasts as new Point()
  longitude: -71.26,
  latitude:  42.09
};

const pointGraphic3D = new Graphic({
  geometry: point,
  symbol: threeDpoint
});

view.graphics.add(pointGraphic3D);

Esri Icon font

The Esri Icon font can be used as the font.family property of the LabelClass for some layers. In the code snippet below, a LabelClass is created by autocasting the symbol type as text, the color, and font. Lastly, we defined the labelPlacement and the labelExpressionInfo.

Layers that can be labeled with Esri Icon font:
CSVLayer, FeatureLayer, GeoJSONLayer, OGCFeatureLayer, StreamLayer, WFSLayer.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
const labelClass = {  // autocasts as new LabelClass()
  symbol: {
    type: 'text',  // autocasts as new TextSymbol()
    color: 'green',
    font: {  // autocast as new Font()
      family: 'CalciteWebCoreIcons',
      size: 12
    }
  },
  labelPlacement: 'above-left',
  labelExpressionInfo: {
    expression: '"\ue61d"'  // esri-icon-map-pin
  }
};

const fl = new FeatureLayer({
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3",
  labelingInfo: labelClass
});

renderPreviewHTML

The symbolUtils class is used to generate small preview images of symbols. This utility can be useful when you have a workflow that requires displaying small previews of symbols used to represent features in a layer. The renderPreviewHTML() method generates a preview image of a given symbol that can be displayed in a custom widget or other DOM element, including a label. The font file (in woff2 format) for this label comes from either our hosted font files, or hosted on a server if using a different source via esriConfig.fontsUrl.

Printing

There are a few considerations to keep in mind when printing a map with labels (printing is currently only supported in 2D MapViews). There is currently no support for printing rotated labels when the map is rotated. Labels cannot be printed as part of a FeatureLayer with ArcGIS Server 10.5.1 or earlier, or with a printing service published with ArcMap. The source for font files must be accessible to the printing service for the labels to appear in a printed map, so if the files are hosted on a private server, the print service must also have access to that private server.

FAQ

This FAQ contains information about useful workflows and answers to common questions!

How do you create new lines in labels?

Labels can be separated into multiple lines using template literals, or using the TextFormatting.NewLine Arcade constant. Here, MARKER_ACTIVITY will be on the first line, and RECAREANAM will be on a new line. Examples:

Use dark colors for code blocksCopy
1
2
3
4
5
// template literal
"$feature.MARKER_ACTIVITY + '\\n' + $feature.RECAREANAM"

// TextFormatting.NewLine
"$feature.MARKER_ACTIVITY + TextFormatting.NewLine + $feature.RECAREANAM"

Where can I find more labeling resources?

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