Hide Table of Contents
What's New archive
Build your first application

This tutorial shows you how to

View the completed app in the JavaScript Sandbox
  • Reference the ArcGIS API for JavaScript
  • Use a basemap from ArcGIS Online
  • Specify the map zoom level and center point
  • Display the map full screen

Note: An alternative version of this tutorial is available that shows how to use ArcGIS API for JavaScript modules in an Asynchronous Module Definition style.

  1. Create a Simple HTML Document

    First, set up a basic HTML document. Here's an example:

    <!DOCTYPE html>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=7,IE=9">
        <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
  2. Reference the ArcGIS API for JavaScript

    To begin working with the ArcGIS API for JavaScript, add the following script and link tags inside the <head> tag:

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

    The script tag loads the ArcGIS API for JavaScript. When new versions of the JavaScript API are released, update the version number to match the newly released version of the API.

    The esri.css style sheet contains styles specific to Esri widgets and components. For more information about this stylesheet, refer to the help topic on required CSS.

    Optionally, include one of the style sheets for a Dojo Dijit theme. There are four themes available: claro, tundra, soria and nihilo. Tundra and claro are used frequently in the API samples. Experiment with different themes and see which you prefer. Again, using a Dojo Dijit theme is optional but doing so is an easy way to get a consistent look and feel to widgets included in the API. The URLs for the various theme style sheets are as follows:

    https://js.arcgis.com/3.46/dijit/themes/claro/claro.css https://js.arcgis.com/3.46/dijit/themes/tundra/tundra.css https://js.arcgis.com/3.46/dijit/themes/nihilo/nihilo.css https://js.arcgis.com/3.46/dijit/themes/soria/soria.css
  3. Load Modules

    Use a second <script> to load specific modules from the API. Instead of having this script tag reference a URL, JavaScript code will be added directly inside of it.


    Putting JavaScript inside a script tag is useful when building simple pages or experimenting but not suitable for larger applications. When building a larger application, all JavaScript should be in separate .js files.

    Modules are loaded using dojo.require() (provided by Dojo). Esri's JavaScript API is built on top of Dojo and relies on Dojo for its module system and other features like vector graphics and localization as well as a way to abstract away browser differences. For more information on the relationship between Dojo and the JavaScript API, see Working with Dojo and Why Dojo.

  4. Ensure the DOM is Available

    Next, use dojo.ready to specify a function that will execute once the DOM is available. The function called by dojo.ready, named init, the map will be created and a new basemap layer will be added to the map. The basemap layer is a service from ArcGIS.com.

      function init() {
        // code to create the map and add a basemap will go here
  5. Create the Map

    A new map is created using esri.Map, which is a reference to the Map class that was loaded from the esri.map module. The string passed to esri.Map, "mapDiv", is the id of the div element that will contain the map. An object to specify other map properties, such as basemap and starting center point and zoom level, is also passed to the Map constructor.

      var map;
      function init() {
        map = new esri.Map("mapDiv", {
          basemap: "topo-vector",
          center: [-122.45, 37.75],
          zoom: 13

    Because the map variable is declared outside of a function that it is a global variable. This is useful while testing/debugging because the browser's developer console can be used to interact with the map.

    Additional basemap options are listed in the esri/basemaps object documentation. Use alternate basemaps by modifying the basemap option in the sandbox.

  6. Define the Page Content

    Now that the JavaScript to create a map is in place, the next step is to add the associated HTML. For this example, the HTML is very simple: a body tag, which defines what is visible in the browser, and a single div element inside the body where the map will be created.

    <body class="claro">
      <div id="mapDiv"></div>

    The div has an id of "mapDiv" to match the id that is passed to the map constructor. The body tag has a class attribute of "claro". This is used to apply styles from claro style sheet included in the head tag of the page to elements (widgets) in the page. If using a different theme, like tundra, use class="tundra".

  7. Style the Page

    For this tutorial, the map fills the browser window. To achieve this, add the following css inside the page's <head> tag:

      html, body, #mapDiv {
        padding: 0;
        margin: 0;
        height: 100%;
Show Modal