Hide Table of Contents
Class: Legend

require(["esri/dijit/Legend"], function(Legend) { /* code goes here */ });


(Added at v2.1)
The legend dijit displays a label and symbol for some or all of the layers in the map. The label and symbol is based on the symbol or renderer for each layer. To view an example of how to set the labels in the legend using a renderer, see this sample.

The legend will respect scale dependencies and only display layers and sublayers that are currently visible in the map. The legend automatically updates if the visibility of a layer or sublayer changes. Optionally, either of these two behaviors can be turned off.

The legend supports the following layer types: ArcGISDynamicMapServiceLayer, ArcGISTiledMapServiceLayer, FeatureLayer, CSVLayer, KMLLayer, and WMSLayer.

If the layer is an ArcGISDynamicMapServiceLayer or ArcGISTiledMapServiceLayer created using ArcGIS Server 10.0 SP1 or higher the legend is generated using the REST Map Service legend resource: http://mapservice-url/legend.

If the layers are version 10 or lower the legend is created using the ArcGIS.com legend service. In order to use the ArcGIS.com legend service your map service needs to be publicly accessible and your application must be able to access ArcGIS.com.


Search for samples that use this class.


new Legend(params, srcNodeRef)Creates a new Legend dijit.


esri/dijit/Legend | Download source

esriLegendGroupLayerDefine the styles for the node that displays group layer information.
esriLegendLayerDefine the style for the node that displays layer swatches.
esriLegendLayerLabelDefine the style for the name and title displayed for layers.
esriLegendMsgClass associated with the div that displays informational messages.
esriLegendServiceDefine the style for the node where the legend item for a service is rendered.
esriLegendServiceLabelDefine the style for the node that displays the name and title of the service.


layerInfosObject[]Specify a subset of the layers in the map to display in the legend.
mapMapReference to the map.


NameReturn typeSummary
destroy()NoneDestroys the legend.
refresh()NoneRefresh the legend.
startup()NoneFinalizes the creation of the legend .
Constructor Details

new Legend(params, srcNodeRef)

Creates a new Legend dijit. Should be called after all the layers have been loaded in the map, typically in the map's onLayerAddResult event.
<Object> params Required Parameters used to configure the dijit. See the list below for details.
<Node | String> srcNodeRef Required Reference or id of the HTML element where the widget should be rendered.
params properties:
<Number> arrangement Optional Specify the alignment of the legend within the HTML element where the legend is rendered. The default value of ALIGN_LEFT displays the symbol on the left side of the label. Valid values are:
<Boolean> autoUpdate Optional When false, the legend will not automatically update if the map changes scale or when layers are added are removed from the map. Call refresh to force a legend update. The default value is true. Added at v3.10
<Object[]> layerInfos Optional Specify a subset of the layers in the map to display in the legend. If not set, all layers in the map will display in the legend. The order of the layers in the legend depends on the layerInfo array. See the layerInfos property description for a description of its object properties.
<Map> map Required Reference to the map.
<Boolean> respectCurrentMapScale Optional When true the legend will update with every scale change and displays only the layers and sub layers that are visible in the current map scale. When false, the legend does not update on every scale change and all layers and sub layers will be displayed. The default value is true.
  "esri.Map", "esri/dijit/Legend", ... 
], function(Map, Legend, ... ) {
  var map = new Map( ... );
  var legend = new Legend({
    map: map
  }, "legendDiv");
Property Details

<Object[]> layerInfos

Specify a subset of the layers in the map to display in the legend. If not set all layers in the map will display in the legend. The order of the layers in the legend depends on the layerInfo array. See the object specifications table for the structure of the layerInfos object.
Object Specifications:
<Boolean> defaultSymbol Optional When false, the default symbol for the renderer will not display in the legend. The default value is true. Only applicable for layers of type esri.layers.FeatureLayer. Added at version 3.1
<Number[]> hideLayers Optional List of sublayer ids that will not be displayed in the legend even if they are visible in the map. Added at version 3.0
<Layer> layer Required A layer to add to the legend. Valid layer types are: ArcGISTiledMapServiceLayer,ArcGISDynamicMapServiceLayer.
<String> title Optional Specify a title for the layer. If no title is specified the service name is used.

<Map> map

Reference to the map. (Added at v3.15)
Method Details


Destroys the legend. Call destroy() when the widget is no longer needed by the application.


Refresh the legend. Takes an optional list of layerInfos to replace the layers setup by the legend constructor. Calling refresh is only necessary when layerInfos is used in the Legend constructor, otherwise the legend will refresh the layers automatically.

legend.refresh([{layer:USLayer, title:'Homeland Security'}]);


Finalizes the creation of the legend . Call startup() after creating the widget when you are ready for user interaction.