This sample demonstrates how to add labels with callouts to a FeatureLayer in a Map component. Callout labels can be used to highlight and point to features in the map without obscuring map data or details.
Callout labels are implemented through the CIMTextSymbol and its associated callout properties.
The currently supported callout types include:
Use the dropdown in the top right corner of the map to select different callout styles for the labels.
<!doctype html><html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" /> <title>Labels with callouts | Sample | ArcGIS Maps SDK for JavaScript</title>
<!-- Load the ArcGIS Maps SDK for JavaScript from CDN --> <script type="module" src="https://js.arcgis.com/5.2/"></script>
<style> html, body { height: 100%; margin: 0; }
#callout-controls { box-sizing: border-box; width: 236px; max-width: calc(100vw - 32px); padding: 12px; background: var(--calcite-color-surface-2); box-shadow: 0 1px 4px rgb(0 0 0 / 20%); }
#callout-controls calcite-label { margin-block-end: 0; } </style> </head> <body> <arcgis-map item-id="0263c98aa8d344c6a427286ef7b95bd3"> <arcgis-zoom slot="top-left"></arcgis-zoom> <div id="callout-controls" slot="top-right"> <calcite-label> Callout style <calcite-select id="callout-style" label="Callout style" disabled> <calcite-option value="background" selected>Background callout</calcite-option> <calcite-option value="balloon">Balloon callout</calcite-option> <calcite-option value="point-symbol">Point symbol callout</calcite-option> <calcite-option value="simple-line">Simple line callout</calcite-option> </calcite-select> </calcite-label> </div> <arcgis-legend slot="bottom-left"></arcgis-legend> </arcgis-map>
<script type="module"> // Load the CIMSymbol class used to update the layer's label symbols. const CIMSymbol = await $arcgis.import("@arcgis/core/symbols/CIMSymbol.js");
const viewElement = document.querySelector("arcgis-map"); const styleSelect = document.querySelector("calcite-select");
// Defines the background callout style. const backgroundCallout = { type: "CIMBackgroundCallout", // The symbol used for the leader line connecting the callout to the feature. leaderLineSymbol: { type: "CIMLineSymbol", symbolLayers: [ { type: "CIMSolidStroke", enable: true, capStyle: "Round", joinStyle: "Round", miterLimit: 4, width: 1, color: [230, 76, 0, 255], }, ], }, lineStyle: "ThreePoint", // The symbol used for the background color and outline of the callout. backgroundSymbol: { type: "CIMPolygonSymbol", symbolLayers: [ { type: "CIMSolidFill", enable: true, color: [255, 255, 255, 255] }, { type: "CIMSolidStroke", enable: true, capStyle: "Round", joinStyle: "Round", miterLimit: 4, width: 1, color: [0, 0, 0, 255], }, ], }, // The symbol used for the accent bar in the background callout. accentBarSymbol: { type: "CIMLineSymbol", symbolLayers: [ { type: "CIMSolidStroke", enable: true, capStyle: "Round", joinStyle: "Round", miterLimit: 4, width: 1, color: [230, 76, 0, 255], }, ], }, // Defines the margin around the text within the callout. margin: { type: "CIMTextMargin", left: 5, right: 5, top: 5, bottom: 5 }, };
// Defines the point symbol used for point symbol callouts. const pointCalloutSymbol = { type: "CIMPointSymbol", symbolLayers: [ { type: "CIMVectorMarker", enable: true, size: 36, frame: { xmin: -20, ymin: -8, xmax: 20, ymax: 8 }, scaleSymbolsProportionally: true, respectFrame: true, markerGraphics: [ { type: "CIMMarkerGraphic", geometry: { rings: [ [ [-20, 0], [0, 8], [20, 0], [0, -8], [-20, 0], ], ], }, symbol: { type: "CIMPolygonSymbol", symbolLayers: [ { type: "CIMSolidFill", enable: true, color: [232, 246, 249, 255] }, { type: "CIMSolidStroke", enable: true, width: 1, color: [0, 94, 110, 255] }, ], }, }, ], }, ], };
// Each option pairs a callout style with the symbol settings it needs. const calloutPresets = { "background": backgroundCallout, "balloon": { type: "CIMBalloonCallout", balloonStyle: "RoundedRectangle", backgroundSymbol: backgroundCallout.backgroundSymbol, leaderTolerance: 0, useFixedDartWidth: false, margin: { left: 5, right: 5, top: 5, bottom: 5 }, }, "point-symbol": { type: "CIMPointSymbolCallout", pointSymbol: pointCalloutSymbol, backgroundScale: "PropUniform", leaderLineSymbol: backgroundCallout.leaderLineSymbol, leaderTolerance: 0, lineStyle: "ThreePoint", gap: 2, }, "simple-line": { type: "CIMSimpleLineCallout", lineSymbol: backgroundCallout.leaderLineSymbol, leaderTolerance: 0, autoSnap: true, }, };
// Defines the text symbol used for labels. const labelTextSymbol = { type: "CIMTextSymbol", fontFamilyName: "Noto Serif", fontStyleName: "Regular", haloSize: 1.5, haloSymbol: { type: "CIMPolygonSymbol", symbolLayers: [{ type: "CIMSolidFill", enable: true, color: [255, 255, 255, 255] }], angleAlignment: "Map", }, height: 10, horizontalAlignment: "Left", symbol: { type: "CIMPolygonSymbol", symbolLayers: [ { type: "CIMSolidStroke", enable: true, capStyle: "Round", joinStyle: "Round", lineStyle3D: "Strip", miterLimit: 10, width: 0, height3D: 1, anchor3D: "Center", color: [255, 255, 255, 255], }, { type: "CIMSolidFill", enable: true, color: [255, 85, 0, 255] }, ], angleAlignment: "Map", }, };
await viewElement.viewOnReady();
// Find the layer from the web map so its existing label rules stay in place. const layer = viewElement.map.allLayers.find((layer) => layer && layer.title === "Mines with Callouts");
if (layer) { const minesLayer = layer; await minesLayer.load(); const originalLabels = minesLayer.labelingInfo;
function updateLabels() { // Start from the map's label rules, then add the selected callout to each one. const callout = calloutPresets[styleSelect.value]; const labelingInfo = [];
for (const originalLabel of originalLabels) { const label = originalLabel.clone(); label.offsetDistance = 10; // adjust callout offset label.symbol = new CIMSymbol({ data: { type: "CIMSymbolReference", // Merge the text symbol with the selected callout symbol: { ...labelTextSymbol, callout }, }, }); labelingInfo.push(label); }
minesLayer.labelingInfo = labelingInfo; }
updateLabels(); // Enable the picker once the layer is ready to show the selected style. styleSelect.addEventListener("calciteSelectChange", updateLabels); styleSelect.disabled = false; } </script> </body></html>