Labeling | ArcGIS Maps SDK for JavaScript

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 if working in 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.

Atkinson Hyperlegible font labeling features on the map — Figure : To maximize readability, especially for visually impaired users, we support the Atkinson Hyperlegible font.

2D labeling

Labeling is supported for most layer types in 2D maps. 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.

There are two labeling mechanisms for 2D labeling: FeatureLayer labeling and MapImageLayer labeling. FeatureLayer refers to layers based-off FeatureLayer, like CSVLayer, GeoJSONLayer, StreamLayer, etc. MapImageLayer refers only to the server-side MapImageLayer.

FeatureLayer LabelClass 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: "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

2D FeatureLayer 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.

For languages with complex text layouts, we added initial support at version 5.1 with the following fonts (future releases may see additional fonts supported):

Noto Sans Khmer Bold
Noto Sans Khmer Regular
Noto Sans Lao Bold
Noto Sans Lao Regular
Noto Sans Myanmar Bold
Noto Sans Myanmar Regular
Noto Sans Thai Bold
Noto Sans Thai Regular

These fonts are treated differently than the other fonts with less complex text layouts, and they will only support their specific languages.

List of fonts currently hosted on https://static.arcgis.com/fonts in pbf and woff2 formats:

Font	Preview	Code
Abril Fatface Regular		Click to copy
Alegreya Bold		Click to copy
Alegreya Bold Italic		Click to copy
Alegreya Italic		Click to copy
Alegreya Regular		Click to copy
Alegreya SC Bold		Click to copy
Alegreya SC Italic		Click to copy
Alegreya SC Regular		Click to copy
Alegreya Sans Italic		Click to copy
Amarante Regular		Click to copy
Amatic SC Bold		Click to copy
Arial Bold		Click to copy
Arial Bold Italic		Click to copy
Arial Italic		Click to copy
Arial Regular		Click to copy
Arial Unicode MS Bold		Click to copy
Arial Unicode MS Regular		Click to copy
Assistant Bold		Click to copy
Assistant Regular		Click to copy
Atkinson Hyperlegible Next Bold		Click to copy
Atkinson Hyperlegible Next Bold Italic		Click to copy
Atkinson Hyperlegible Next Regular		Click to copy
Atkinson Hyperlegible Next Regular Italic		Click to copy
Atomic Age Regular		Click to copy
Audiowide Regular		Click to copy
Avenir Next LT Pro Bold		Click to copy
Avenir Next LT Pro Bold Italic		Click to copy
Avenir Next LT Pro Demi Italic		Click to copy
Avenir Next LT Pro Light Italic		Click to copy
Avenir Next LT Pro Light Regular		Click to copy
Avenir Next LT Pro Medium Bold		Click to copy
Avenir Next LT Pro Medium Bold Italic		Click to copy
Avenir Next LT Pro Regular		Click to copy
Avenir Next LT Pro Regular Bold		Click to copy
Avenir Next LT Pro Regular Bold Italic		Click to copy
Avenir Next LT Pro Regular Italic		Click to copy
BC Sans Bold		Click to copy
BC Sans Italic		Click to copy
BC Sans Regular		Click to copy
Barlow Bold		Click to copy
Barlow Bold Italic		Click to copy
Barlow Condensed Bold		Click to copy
Barlow Condensed Bold Italic		Click to copy
Barlow Condensed Italic		Click to copy
Barlow Condensed Light Italic		Click to copy
Barlow Condensed Medium Italic		Click to copy
Barlow Condensed Regular		Click to copy
Barlow Italic		Click to copy
Barlow Light Italic		Click to copy
Barlow Medium Italic		Click to copy
Barlow Regular		Click to copy
BellTopo Sans Bold		Click to copy
BellTopo Sans Bold Italic		Click to copy
BellTopo Sans Italic		Click to copy
BellTopo Sans Regular		Click to copy
Belleza Regular		Click to copy
Black Ops One Regular		Click to copy
Cabin Sketch Bold		Click to copy
Cabin Sketch Regular		Click to copy
Carrois Gothic SC Regular		Click to copy
Caveat Bold		Click to copy
Coming Soon Regular		Click to copy
Dongle Bold		Click to copy
Dongle Regular		Click to copy
Edu NSW ACT Foundation Bold		Click to copy
Edu NSW ACT Foundation Regular		Click to copy
FGDC GeoAge Regular		Click to copy
FZ Script Regular		Click to copy
Fira Mono Bold		Click to copy
Fira Mono Regular		Click to copy
Gochi Hand Regular		Click to copy
Homemade Apple Regular		Click to copy
IM Fell DW Pica PRO Italic		Click to copy
IM Fell DW Pica PRO Regular		Click to copy
Inter Bold		Click to copy
Inter Regular		Click to copy
Itim Regular		Click to copy
Josefin Sans Bold		Click to copy
Josefin Sans Bold Italic		Click to copy
Josefin Sans Italic		Click to copy
Josefin Sans Medium Italic		Click to copy
Josefin Sans Regular		Click to copy
Josefin Sans Semibold Italic		Click to copy
Josefin Slab Bold		Click to copy
Josefin Slab Bold Italic		Click to copy
Josefin Slab Italic		Click to copy
Josefin Slab Light Italic		Click to copy
Josefin Slab Regular		Click to copy
Josefin Slab Thin Italic		Click to copy
Just Another Hand Regular		Click to copy
Kranky Regular		Click to copy
Laila Bold		Click to copy
Laila Regular		Click to copy
Life Savers Bold		Click to copy
Loved by the King Regular		Click to copy
Merriweather Bold		Click to copy
Merriweather Bold Italic		Click to copy
Merriweather Italic		Click to copy
Merriweather Regular		Click to copy
Montserrat Bold		Click to copy
Montserrat Italic		Click to copy
Montserrat Medium Italic		Click to copy
Montserrat Regular		Click to copy
Montserrat Semibold Italic		Click to copy
Noto Sans Bold		Click to copy
Noto Sans Bold Italic		Click to copy
Noto Sans Italic		Click to copy
Noto Sans Khmer Bold		Click to copy
Noto Sans Khmer Regular		Click to copy
Noto Sans Lao Bold		Click to copy
Noto Sans Lao Regular		Click to copy
Noto Sans Myanmar Bold		Click to copy
Noto Sans Myanmar Regular		Click to copy
Noto Sans Regular		Click to copy
Noto Sans Thai Bold		Click to copy
Noto Sans Thai Regular		Click to copy
Noto Serif Bold		Click to copy
Noto Serif Bold Italic		Click to copy
Noto Serif Italic		Click to copy
Noto Serif Regular		Click to copy
Old Standard TT Bold		Click to copy
Old Standard TT Italic		Click to copy
Old Standard TT Regular		Click to copy
Orbitron Bold		Click to copy
Orbitron Regular		Click to copy
Oregano Italic		Click to copy
Oregano Regular		Click to copy
Oswald Bold		Click to copy
Oswald Regular		Click to copy
Pacifico Regular		Click to copy
Palatino Linotype Regular		Click to copy
Patrick Hand Regular		Click to copy
Playfair Display Bold		Click to copy
Playfair Display Bold Italic		Click to copy
Playfair Display Italic		Click to copy
Playfair Display Regular		Click to copy
Playfair Display SC Bold		Click to copy
Playfair Display SC Regular		Click to copy
Radio Canada Semicondensed Bold		Click to copy
Radio Canada Semicondensed Bold Italic		Click to copy
Radio Canada Semicondensed Italic		Click to copy
Radio Canada Semicondensed Medium Italic		Click to copy
Radio Canada Semicondensed Regular		Click to copy
Redressed Regular		Click to copy
Risque Regular		Click to copy
Roboto Bold		Click to copy
Roboto Bold Italic		Click to copy
Roboto Condensed Italic		Click to copy
Roboto Condensed Light Italic		Click to copy
Roboto Italic		Click to copy
Roboto Medium Italic		Click to copy
Roboto Regular		Click to copy
Rye Regular		Click to copy
Special Elite Regular		Click to copy
Stix Two Text Bold		Click to copy
Stix Two Text Bold Italic		Click to copy
Stix Two Text Italic		Click to copy
Stix Two Text Medium Italic		Click to copy
Stix Two Text Regular		Click to copy
Syncopate Bold		Click to copy
Syncopate Regular		Click to copy
Tangerine Bold		Click to copy
Tangerine Regular		Click to copy
Ubuntu Bold		Click to copy
Ubuntu Bold Italic		Click to copy
Ubuntu Condensed Regular		Click to copy
Ubuntu Italic		Click to copy
Ubuntu Light Bold		Click to copy
Ubuntu Light Bold Italic		Click to copy
Ubuntu Light Italic		Click to copy
Ubuntu Medium Italic		Click to copy
Ubuntu Mono Bold		Click to copy
Ubuntu Mono Bold Italic		Click to copy
Ubuntu Mono Italic		Click to copy
Ubuntu Mono Regular		Click to copy
Ubuntu Regular		Click to copy
UnifrakturCook Bold		Click to copy
Vast Shadow Regular		Click to copy
Walter Turncoat Regular		Click to copy

Preview:N/A:

Code:

Click to copy

2D 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 Map depend on the fonts installed on the ArcGIS Server that published the layer. This is the same for 2D maps and 3D scenes. 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

3D 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.

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)

Currently a feature can only have one label. If a feature satisfies the where condition of multiple LabelClasses, then only the label corresponding to the first matching LabelClass is displayed.
Label placement only applies to Point layers.
If the TextSymbol3DLayer.size property is set, it will override the Font.size property.

Sample: Flat vs. volumetric 3D symbol layers

3D fonts

The supported font families for 3D scenes 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:

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

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:

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

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.

Custom fonts and disconnected environments

In 2D maps, 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 config.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.

View	Applied to	Font source
2D & 3D	MapImageLayer	User’s computer and web browser (`ttf`, `otf`, `woff`, or `woff2` format)
2D & 3D	renderPreviewHTML	`https://static.arcgis.com/fonts/woff2` (`woff2` format) hosted on a server (`woff2` format)
2D maps	Non-MapImageLayer	`https://static.arcgis.com/fonts` (`pbf` format) hosted on a server (`pbf` format) and `https://static.arcgis.com/fonts/woff2` (`woff2` format) hosted on a server (`woff2` format)
3D scenes	Non-MapImageLayer	User’s computer and web browser `https://static.arcgis.com/fonts/woff2` (`woff2` format) referenced from a server (`ttf`, `otf`, `woff`, or `woff2` format)

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

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:

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:

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.

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 config.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!

Where do fonts come from?

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

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:

// template literal
"$feature.MARKER_ACTIVITY + '\\n' + $feature.RECAREANAM";

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

Where can I find more labeling resources?

What about labels from basemaps?

A basemap can contain base layers, which comprise one or more layers, and reference layers. Reference layers are displayed on top of the base layer and all other layers in the map, and can be used to display labels on top of terrain or streets. Labels from reference layers will be placed at the top, and labels from base layers will display at the same level as the basemap’s base layers.

ReferenceEsri Icon Font ReferenceMigrating from 3.x