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.

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.

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]
});

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.

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):

Font	Preview	Code
Abril Fatface Regular		Copy
Alegreya Bold		Copy
Alegreya Bold Italic		Copy
Alegreya Italic		Copy
Alegreya Regular		Copy
Alegreya SC Bold		Copy
Alegreya SC Italic		Copy
Alegreya SC Regular		Copy
Alegreya Sans Italic		Copy
Amarante Regular		Copy
Amatic SC Bold		Copy
Arial Bold		Copy
Arial Bold Italic		Copy
Arial Italic		Copy
Arial Regular		Copy
Arial Unicode MS Bold		Copy
Arial Unicode MS Regular		Copy
Atomic Age Regular		Copy
Audiowide Regular		Copy
Avenir Next LT Pro Bold		Copy
Avenir Next LT Pro Bold Italic		Copy
Avenir Next LT Pro Demi Italic		Copy
Avenir Next LT Pro Italic		Copy
Avenir Next LT Pro Light		Copy
Avenir Next LT Pro Light Italic		Copy
Avenir Next LT Pro Medium Bold		Copy
Avenir Next LT Pro Medium Bold Italic		Copy
Avenir Next LT Pro Regular		Copy
Avenir Next LT Pro Regular Bold		Copy
BellTopo Sans Bold		Copy
BellTopo Sans Bold Italic		Copy
BellTopo Sans Italic		Copy
BellTopo Sans Regular		Copy
Belleza Regular		Copy
Black Ops One Regular		Copy
Cabin Sketch Bold		Copy
Cabin Sketch Regular		Copy
Coming Soon Regular		Copy
FGDC GeoAge Regular		Copy
Homemade Apple Regular		Copy
IM FELL DW Pica PRO Italic		Copy
IM FELL DW Pica PRO Regular		Copy
Josefin Sans Regular		Copy
Josefin Sans Semibold Italic		Copy
Josefin Slab Bold		Copy
Josefin Slab Bold Italic		Copy
Josefin Slab Italic		Copy
Josefin Slab Light Italic		Copy
Josefin Slab Regular		Copy
Josefin Slab Thin Italic		Copy
Just Another Hand Regular		Copy
Kranky Regular		Copy
Life Savers Bold		Copy
Loved by the King Regular		Copy
Merriweather Bold		Copy
Merriweather Bold Italic		Copy
Merriweather Italic		Copy
Merriweather Regular		Copy
Montserrat Bold		Copy
Montserrat Italic		Copy
Montserrat Medium Italic		Copy
Montserrat Regular		Copy
Montserrat Semibold Italic		Copy
Noto Sans Bold		Copy
Noto Sans Bold Italic		Copy
Noto Sans Italic		Copy
Noto Sans Regular		Copy
Noto Serif Bold		Copy
Noto Serif Bold Italic		Copy
Noto Serif Italic		Copy
Noto Serif Regular		Copy
Old Standard TT Bold		Copy
Old Standard TT Italic		Copy
Old Standard TT Regular		Copy
Orbitron Bold		Copy
Orbitron Regular		Copy
Oregano Italic		Copy
Oregano Regular		Copy
Oswald Bold		Copy
Oswald Regular		Copy
Pacifico Regular		Copy
Palatino Linotype Regular		Copy
Playfair Display Black		Copy
Playfair Display Bold		Copy
Playfair Display Bold Italic		Copy
Playfair Display Italic		Copy
Playfair Display Regular		Copy
Playfair Display SC Bold		Copy
Playfair Display SC Regular		Copy
Redressed Regular		Copy
Risque Regular		Copy
Roboto Bold		Copy
Roboto Bold Italic		Copy
Roboto Condensed Italic		Copy
Roboto Condensed Light Italic		Copy
Roboto Italic		Copy
Roboto Regular		Copy
Rye Regular		Copy
Special Elite Regular		Copy
Syncopate Bold		Copy
Syncopate Regular		Copy
Tangerine Regular		Copy
Ubuntu Bold		Copy
Ubuntu Bold Italic		Copy
Ubuntu Condensed Regular		Copy
Ubuntu Italic