Hide Table of Contents
Required CSS

Esri CSS

Starting with version 3.2 of the ArcGIS API for JavaScript, developers must include an additional Cascading Style Sheet (CSS) file: esri.css.

The URL for this file is:

// versions 3.11 and forward
<link rel="stylesheet" href="https://js.arcgis.com/API-VERSION/esri/css/esri.css">

// versions prior to 3.11
<link rel="stylesheet" href="https://js.arcgis.com/API-VERSION/js/esri/css/esri.css">

For instance, this CSS file would be included via a link tag:

<link rel="stylesheet" href="https://js.arcgis.com/3.20/esri/css/esri.css">

The esri.css file contains the CSS for various widgets, including CSS for the map. Because all CSS is in a single file, retrieving CSS for the API is done in a single request. Reducing the number of http requests is one way for apps to improve performance.

Dojo specific CSS

The esri.css file does not include the CSS for various Dojo widgets or themes like tundra or claro; those files must be included separately. Exceptions are the Grid and RangeSlider, which are used by widgets in the API. Grid styles must be explicitly included.

For instance, this CSS file would be included via an additional link tag:

<link rel="stylesheet" href="https://js.arcgis.com/3.20/dijit/themes/claro/claro.css">

Legacy CSS

Prior to version 3.2, CSS files were appended to a page's DOM dynamically via JavaScript. Dynamically appending CSS files makes overriding default styles cumbersome because CSS included via a link or style tag is parsed before JavaScript appends CSS to a page. This results in having to use !important to override default widget styles. Because widgets have been refactored to not dynamically append their CSS, !important is no longer necessary. API versions prior to 3.2 have not been modified so it is still necessary to use !important with older versions. Explicitly including CSS via a link tag instead of dynamically appending CSS also follows the convention used by components that ship with Dojo.

Esri CSS contents

The publicly hosted version of esri.css, as well as the one available for download, is a minified and concatenated (but not obfuscated) version of the following files generated by the Dojo build system (all URLs are relative to esri.css):

  • jsapi.css
  • ../toolbars/css/edit.css
  • ../dijit/css/AttributeInspector.css
  • ../dijit/css/BasemapGallery.css
  • ../dijit/css/BasemapToggle.css
  • ../dijit/css/Bookmarks.css
  • ../dijit/css/Directions.css
  • ../dijit/css/Gallery.css
  • ../dijit/css/Geocoder.css
  • ../dijit/css/Gauge.css
  • ../dijit/css/HomeButton.css
  • ../dijit/css/InfoWindow.css
  • ../dijit/css/LayerSwipe.css
  • ../dijit/css/Legend.css
  • ../dijit/css/LocateButton.css
  • ../dijit/css/Measurement.css
  • ../dijit/css/OverviewMap.css
  • ../dijit/css/PopupFont.css
  • ../dijit/css/Popup.css
  • ../dijit/css/PopupMobile.css
  • ../dijit/css/MultidimensionalFilter.css
  • ../dijit/css/ImageServiceMeasure.css
  • ../dijit/css/Print.css
  • ../dijit/css/Scalebar.css
  • ../../dojox/form/resources/RangeSlider.css
  • ../dijit/css/TimeSlider.css
  • ../dijit/css/MultidimensionalSlider.css
  • ../dijit/css/VectorFieldRenderer.css
  • ../dijit/css/MultidimensionalFilter.css
  • ../dijit/css/temporal.css
  • ../dijit/css/RenderingRule.css
  • ../dijit/css/MosaicRule.css
  • ../dijit/editing/css/attachment.css
  • ../dijit/editing/css/drawingToolbar.css
  • ../dijit/editing/css/editor.css
  • ../../dojox/grid/resources/Grid.css
  • ../dijit/editing/css/TemplatePicker.css
  • ../../dojox/form/resources/CheckedMultiSelect.css
  • ../../dojox/widget/TitleGroup/TitleGroup.css
  • ../dijit/css/BrowseItems.css
  • ../dijit/analysis/css/analysis.css
  • ../dijit/css/SingleFilter.css
  • ../dijit/css/SymbolEditor.css
  • ../dijit/HaloStyler/css/HaloStyler.css
  • ../dijit/css/FontAlignment.css
  • ../dijit/css/CalculateField.css
  • ../dijit/geoenrichment/themes/common/main.css
  • ../dijit/ColorPicker/css/ColorPicker.css
  • ../dijit/HorizontalSlider/css/HorizontalSlider.css
  • ../dijit/VisibleScaleRangeSlider/css/VisibleScaleRangeSlider.css
  • ../dijit/SymbolStyler/css/SymbolStyler.css
  • ../dijit/SymbolStyler/css/MarkerSymbolPicker.css
  • ../dijit/SymbolStyler/css/ColorRampPicker.css
  • ../dijit/css/Tags.css
  • ../dijit/FeatureTable/css/master.css
  • ../dijit/RendererSlider/css/RendererSlider.css
  • ../dijit/Search/css/Search.css
  • ../dijit/LayerList/css/LayerList.css
  • ../themes/calcite/icons/style.css
  • ../themes/calcite/icons/ie7/ie7.css
  • ../dijit/ObliqueViewer/css/ObliqueRotationWidget.css
  • ../dijit/ObliqueViewer/css/RasterList.css

Again, paths are relative to esri.css but are not used by the API, by default. It is possible to include component-specific CSS files in an app but it is not recommended since all CSS is minified and concatenated in esri.css. Most applications will perform best by using esri.css. Most paths and file names accurately describe the component of the API they style. The exception is jsapi.css, which styles the map, the attribution widget and the various slider options available for use with a map's zoom slider.

Calcite (beta)

Since version 3.16 the API includes a new theme - Calcite. To use it, just add the following CSS to your app:

<link rel="stylesheet" href="https://js.arcgis.com/3.20/esri/themes/calcite/dijit/calcite.css">
<link rel="stylesheet" href="https://js.arcgis.com/3.20/esri/themes/calcite/esri/esri.css">

instead of the regular:

<link rel="stylesheet" href="https://js.arcgis.com/3.20/esri/css/esri.css">

You also need to set the body class to calcite:

<body class="calcite">

This theme is in beta and does not support all components of the API. The following widgets are supported:

Advanced workflows

In certain situations, developers may need to isolate component-specific CSS files and their assets. Developers utilizing CSS preprocessors to build their own custom single CSS application file and instances where optimizing applications to the extreme may justify not using the esri.css. Proceed with caution as this introduces many additional resources that must be managed. The majority of developers should adhere to using the esri.css.