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.
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.
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
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
in://static.arcgis.com/fonts pbf
format - From
https
in://static.arcgis.com/fonts/woff2 woff2
format - Referenced from a server in
pbf
,otf
,ttf
,woff
, orwoff2
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 > Publishing
(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
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
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 | ||
Alegreya Bold | ||
Alegreya Bold Italic | ||
Alegreya Italic | ||
Alegreya Regular | ||
Alegreya SC Bold | ||
Alegreya SC Italic | ||
Alegreya SC Regular | ||
Alegreya Sans Italic | ||
Amarante Regular | ||
Amatic SC Bold | ||
Arial Bold | ||
Arial Bold Italic | ||
Arial Italic | ||
Arial Regular | ||
Arial Unicode MS Bold | ||
Arial Unicode MS Regular | ||
Atomic Age Regular | ||
Audiowide Regular | ||
Avenir Next LT Pro Bold | ||
Avenir Next LT Pro Bold Italic | ||
Avenir Next LT Pro Demi Italic | ||
Avenir Next LT Pro Italic | ||
Avenir Next LT Pro Light | ||
Avenir Next LT Pro Light Italic | ||
Avenir Next LT Pro Medium Bold | ||
Avenir Next LT Pro Medium Bold Italic | ||
Avenir Next LT Pro Regular | ||
Avenir Next LT Pro Regular Bold | ||
BellTopo Sans Bold | ||
BellTopo Sans Bold Italic | ||
BellTopo Sans Italic | ||
BellTopo Sans Regular | ||
Belleza Regular | ||
Black Ops One Regular | ||
Cabin Sketch Bold | ||
Cabin Sketch Regular | ||
Coming Soon Regular | ||
FGDC GeoAge Regular | ||
Homemade Apple Regular | ||
IM FELL DW Pica PRO Italic | ||
IM FELL DW Pica PRO Regular | ||
Josefin Sans Regular | ||
Josefin Sans Semibold Italic | ||
Josefin Slab Bold | ||
Josefin Slab Bold Italic | ||
Josefin Slab Italic | ||
Josefin Slab Light Italic | ||
Josefin Slab Regular | ||
Josefin Slab Thin Italic | ||
Just Another Hand Regular | ||
Kranky Regular | ||
Life Savers Bold | ||
Loved by the King Regular | ||
Merriweather Bold | ||
Merriweather Bold Italic | ||
Merriweather Italic | ||
Merriweather Regular | ||
Montserrat Bold | ||
Montserrat Italic | ||
Montserrat Medium Italic | ||
Montserrat Regular | ||
Montserrat Semibold Italic | ||
Noto Sans Bold | ||
Noto Sans Bold Italic | ||
Noto Sans Italic | ||
Noto Sans Regular | ||
Noto Serif Bold | ||
Noto Serif Bold Italic | ||
Noto Serif Italic | ||
Noto Serif Regular | ||
Old Standard TT Bold | ||
Old Standard TT Italic | ||
Old Standard TT Regular | ||
Orbitron Bold | ||
Orbitron Regular | ||
Oregano Italic | ||
Oregano Regular | ||
Oswald Bold | ||
Oswald Regular | ||
Pacifico Regular | ||
Palatino Linotype Regular | ||
Playfair Display Black | ||
Playfair Display Bold | ||
Playfair Display Bold Italic | ||
Playfair Display Italic | ||
Playfair Display Regular | ||
Playfair Display SC Bold | ||
Playfair Display SC Regular | ||
Redressed Regular | ||
Risque Regular | ||
Roboto Bold | ||
Roboto Bold Italic | ||
Roboto Condensed Italic | ||
Roboto Condensed Light Italic | ||
Roboto Italic | ||
Roboto Regular | ||
Rye Regular | ||
Special Elite Regular | ||
Syncopate Bold | ||
Syncopate Regular | ||
Tangerine Regular | ||
Ubuntu Bold | ||
Ubuntu Bold Italic | ||
Ubuntu Condensed Regular | ||
Ubuntu Italic | ||
Ubuntu Light | ||
Ubuntu Light Bold | ||
Ubuntu Light Bold Italic | ||
Ubuntu Light Italic | ||
Ubuntu Medium Italic | ||
Ubuntu Mono Bold | ||
Ubuntu Mono Bold Italic | ||
Ubuntu Mono Italic | ||
Ubuntu Mono Regular | ||
Ubuntu Regular | ||
UnifrakturCook Bold | ||
Vast Shadow Regular | ||
Walter Turncoat Regular |
{}
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
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
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]
});
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
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\
heading. These fonts are available via https
. 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 fonts
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.
View | Applied to | Font source |
---|---|---|
2D & 3D | MapImageLayer | User's computer and web browser (ttf , otf , woff , or woff2 format) |
2D & 3D | renderPreviewHTML | https (woff2 format)hosted on a server ( woff2 format) |
2D MapView | Non-MapImageLayer | https (pbf format)hosted on a server ( pbf format) |
3D SceneView | Non-MapImageLayer | User's computer and web browserhttps (woff2 format)referenced from a server ( ttf , otf , woff , or woff2 format) |
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:
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 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:
// template literal
"$feature.MARKER_ACTIVITY + '\\n' + $feature.RECAREANAM"
// TextFormatting.NewLine
"$feature.MARKER_ACTIVITY + TextFormatting.NewLine + $feature.RECAREANAM"