Hide Table of Contents
Class: Scalebar

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


(Added at v2.1)
The Scalebar widget displays a scalebar on the map or in a specified HTML node. The widget respects various coordinate systems and displays units in English or metric values. When working with Web Mercator or geographic coordinate systems, including the planetary ones listed below) the scalebar takes into account projection distortion and dynamically adjusts the scalebar. The Scalebar sample, which uses a map using the Web Mercator projection, shows this behavior. Open the sample and note that as you pan the map south towards the equator the scalebar gets shorter and as you pan north it gets longer.

Supported planetary coordinate systems: 104900 (GCS_Mercury_2000), 104901 (GCS_Venus_1985), 104902 (GCS_Venus_2000), 104903 (GCS_Moon_2000), 104904 (GCS_Mars_1979), 104905 (GCS_Mars_2000), 104906 (GCS_Deimos_2000), 104907 (GCS_Phobos_2000), 104912 (GCS_Callisto_2000), 104915 (GCS_Europa_2000), 104916 (GCS_Ganymede_2000), 104918 (GCS_Io_2000), 104929 (GCS_Enceladus_2000), 104943 (GCS_Titan_2000), 104971 (Mars 2000 (Sphere)), 104972 (1 Ceres 2015), 104973 (4 Vesta 2015), and 104974 (Mercury 2015).

When the scalebar is inside the map, the actual location of the scalebar is used to calculate the scale. When the scalebar is positioned outside the map div the following values are used:
  • If the scalebar is above the map, the upper border of the map is used.
  • If the scalebar is below the map, the lower border of the map is used.
  • If the scalebar is positioned next to the map, its vertical location is used.


Search for samples that use this class.


new Scalebar(params, srcNodeRef?)Creates a new Scalebar dijit.


esri/dijit/Scalebar | Download source

esriScalebarDefine the styles for the scalebar dijit. In this snippet extra padding is added around the scalebar.
.esriScalebar{padding: 20px 20px;}
esriScalebarLabelDefine the styles for the scalebar labels. Use this CSS class to define label properties like font and color.
esriScalebarLineDefine scalebar styles when the scalebarStyle has been set to line.
esriScalebarRulerDefine the styles for the scalebar ruler. Use this CSS class to deifne properties like the background color and border for the ruler.
esriScalebarRulerBlockDefine the styles for the scalebar ruler blocks. Use this CSS class to define ruler block properties like color.
esriScalebarSecondNumberDefine the styles for the last number in the scalebar labels.


NameReturn typeSummary
destroy()NoneDestroy the scalebar.
hide()NoneHide the scalebar dijit.
show()NoneSet the scalebar's visibility to true.
startup()NoneFinalizes the creation of the widget.
Constructor Details

new Scalebar(params, srcNodeRef?)

Creates a new Scalebar dijit. The Scalebar constructor should be called after the map is loaded, e.g., in the map's .on("load") event.
<Object> params Required Parameters used to configure the widget. See the list below for details.
<Node | String> srcNodeRef Optional Reference or id of the HTML element where the widget should be rendered.
params properties:
<String> attachTo Optional Specify the scalebar position on the map. Valid options are "top-right","bottom-right","top-center","bottom-center","bottom-left","top-left". The default value is "bottom-left".
<Map> map Required Reference to the map.
<String> scalebarStyle Optional Specify the style for the scalebar. Valid values are "ruler" or "line". When scalebarUnit is set to dual the scalebar style will be set to line. Added at v3.4
<String> scalebarUnit Optional Specify the scalebar units. Valid values are "english" or "metric" and starting at version 3.4 "dual". When using dual the scalebar displays both english and metric units. The default value is "english".
  "esri/map", "esri/dijit/Scalebar", ... 
], function(Map, Scalebar, ... ) {
  var map = new Map( ... );
  var scalebar = new Scalebar({
    map: map,
    attachTo: "top-right"
Method Details


Destroy the scalebar. Call this method when the scalebar is no longer needed by the application. (Added at v2.5)


Hide the scalebar dijit.




Set the scalebar's visibility to true. This method only applies if the scalebar has been hidden using scalebar.hide.




Finalizes the creation of the widget. (Added at v3.13)