Legend | API Reference | ArcGIS API for JavaScript

The legend dijit displays a label and symbol for some or all of the layers in the map. If specified, the legend will respect scale dependencies and only display layers and sub layers that are currently visible in the map. The legend automatically updates if the visibility of a layer or sublayer changes.

The legend supports the following layer types: ArcGISDynamicMapServiceLayer, ArcGISTiledMapServiceLayer, FeatureLayer and KMLLayer. 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.

The legend for feature layers is created using the layer's drawing info, for example:

http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Earthquakes/EarthquakesFromLastSevenDays/MapServer/0

Samples

Search for samples that use this class.

Class hierarchy

esri.dijit.Legend

Constructors

Constructor	Description
new esri.dijit.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.

CSS

CSS Class	Description
esriLegendService	Define the style for the node where the legend item for a service is rendered.
esriLegendServiceLabel	Define the style for the node that displays the name and title of the service.
esriLegendGroupLayer	Define the styles for the node that displays group layer information.
esriLegendLayerLabel	Define the style for the name and title displayed for layers.
esriLegendLayer	Define the style for the node that displays layer swatches.

Methods

Method	Return Value	Description
destroy()	None	Destroys the legend. Call destroy() when the widget is no longer needed by the application.
refresh()	None	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.
startup()	None	Finalizes the creation of the legend . Call startup() after creating the widget when you are ready for user interaction.

Constructor Details

new esri.dijit.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.

Parameters:

<Object> params	Required	Parameters used to configure the dijit. See the list below for details.
<String> srcNodeRef	Required	Reference or id of the HTML element where the widget should be rendered.

Options:

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

esri.dijit.Legend.ALIGN_LEFT
esri.dijit.Legend.ALIGN_RIGHT

<Boolean> autoUpdate

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. (As of v3.0)

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

Array of result objects with the following properties.

<boolean>defaultSymbol	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. (As of v3.1)
<number[]>hideLayers	List of sublayer ids that will not be displayed in the legend even if they are visible in the map. (As of v3.0)
<layer> layer	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.

{layer:quakeLayer,title:'Earthquakes'}

<Map> map

Reference to the map. The map parameter is required.

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

Code Snippet:

var legend = new esri.dijit.Legend({
  map:map
},"legendDiv");
legend.startup();

Method Details

destroy()

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

refresh()

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.

Code Snippet:

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

startup()

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

Code Snippet:

legend.startup();