Geocoder widget | Guide | ArcGIS API for JavaScript 3.46

The Geocoder widget was deprecated in version 3.13 and replaced by the Search widget. Apps created with version 3.13 or later should use the Search widget instead of the Geocoder widget.

Please see the Search widget tutorial.

This tutorial covers the following:

Introduction to the Geocoder widget
Require modules
Create an element in your HTML document to house the widget
Specify a style to position the widget over the map and make the map fill the entire page
Instantiate the widget
Enable auto-complete
Show selected result on the map
Using Placeholder Text
Create a spotlight effect
Putting it all together
Bonus: Use a custom geocoder

Introduction to the Geocoder widget

Panning and zooming a map to get to the place you'd like to go can be time consuming and a pain in your wrist. One way to provide easier map navigation is by adding a search box. A search box lets users to jump to a location quickly and easily.

Now it's easier to add a search box that does just that by using the Geocoder widget with the ArcGIS Global Geocoding service.

View a live version of a samples that uses the Geocoder widget in the ArcGIS API for JavaScript Sandbox. The sandbox is a live code editor that allows you to modify the sample's source and view the changes live.

In this tutorial, you will add the Geocoder widget to a basic web map to allow your users to easily search for locations. Once added, we'll go through a few customizations that can be applied to the Geocoder widget.

Require modules

Require the widget and additional modules.

require([
  "esri/map",
  "esri/dijit/Geocoder",
  "esri/graphic",
  "esri/symbols/SimpleMarkerSymbol",
  "esri/geometry/screenUtils",
  "dojo/dom",
  "dojo/dom-construct",
  "dojo/query",
  "dojo/_base/Color"
], function(
  Map, Geocoder, Graphic, SimpleMarkerSymbol, screenUtils, dom, domConstruct, query, Color) {
  // create a map and instance of the geocoder widget here
});

Create an element in your HTML document to house the widget.

<body>
  <div id="search"></div>
  <div id="map"></div>
</body>

Specify a style to position the widget over the map and make the map fill the entire page.

<style>
  html, body, #map {
    height: 100%;
    width: 100%;
    margin: 0;
    padding: 0;
  }
  #search {
    display: block;
    position: absolute;
    z-index: 3;
    top: 20px;
    left: 75px;
  }
</style>

Instantiate the widget

Create a map and create an instance of the Geocoder widget. As the second parameter to the Geocoder constructor, pass a reference to the node where you want to attach the widget. This node already exists in our HTML document and has a an ID of "search". This sample specifies the minimum required Geocoder parameters. After creating the widget, be sure to call startup().
```
var map = new Map("map", {
  basemap: "topo-vector",
  center: [ -100, 40 ],
  zoom: 10
});
var geocoder = new Geocoder({
  map: map,
}, dom.byId("search"));
geocoder.startup();
```
At this point, we have the default Geocoder widget in the page:
Enable auto-complete

The Geocoder widget has additional capabilities such as address auto-complete that can be enabled by setting geocoder options. Set the autoComplete option to true to display a list of potential locations as users are typing.
```
var geocoder = new Geocoder({
  autoComplete: true,
  map: map
}, dom.byId("search"));
```
Below is a screen shot of what the Geocoder widget looks like with auto-complete enabled:

Show selected result on the map

Next we'll add code to the application to add a symbol and display an info window for the found location.

geocoder.on("select", showLocation);

function showLocation(evt) {
  map.graphics.clear();
  var point = evt.result.feature.geometry;
  var symbol = new SimpleMarkerSymbol()
    .setStyle("square")
    .setColor(new Color([255,0,0,0.5]));
  var graphic = new Graphic(point, symbol);
  map.graphics.add(graphic);

  map.infoWindow.setTitle("Search Result");
  map.infoWindow.setContent(evt.result.name);
  map.infoWindow.show(evt.result.feature.geometry);
});

Using Placeholder Text

In this step the Geocoder code is updated to define custom text to appear in the Geocoder search box. This text provides a hint to users about what they should enter in the search box. Specify the custom text by setting the placeholder option for the geocoder.
```
var geocoder =  new Geocoder({
  arcgisGeocoder: {
    placeholder: "Find a place"
  },
  map: map
}, dom.byId("search"));
```
After adding the placeholder option the Geocoder displays the text in the widget itself:

Create a spotlight effect

The next couple of code snippets will add a spotlight effect highlight the selected location.

First, define the css styles that determine how the spotlight effect will look. Put the following inside an existing <style> tag:

.spotlight {
  z-index:-1;
  position:absolute;
  left:50%;
  top:50%;
  border-radius:50%;
  opacity:0;
  box-shadow:
  inset rgba(0,0,0,0.25) 0px 0px 20px 20px,
  rgba(0,0,0,0.25) 0px 0px 0px 1000px;
  transition:all 1000ms;
  -moz-transition:all 1000ms;
  -webkit-transition:all 1000ms;
}
.spotlight-active {
  z-index:2;
  opacity:1;
}

Add code that adds a spotlight div to the map container once the map loads.

map.on("load", enableSpotlight);

function enableSpotlight() {
  var html = "<div id='spotlight' class='spotlight'></div>"
  domConstruct.place(html, dom.byId("map_container"), "first");
}

When a result is clicked or the enter key is pressed, add the spotlight to the map. Modify the showLocation function to be:

function showLocation(evt) {
  map.graphics.clear();
  var point = evt.result.feature.geometry;
  var symbol = new SimpleMarkerSymbol().setStyle(
    SimpleMarkerSymbol.STYLE_SQUARE).setColor(
    new Color([255,0,0,0.5])
  );
  var graphic = new Graphic(point, symbol);
  map.graphics.add(graphic);

  map.infoWindow.setTitle("Search Result");
  map.infoWindow.setContent(evt.result.name);
  map.infoWindow.show(evt.result.feature.geometry);

  var spotlight = map.on("extent-change", function(extentChange) {
    var geom = screenUtils.toScreenGeometry(map.extent, map.width, map.height, extentChange.extent);
    var width = geom.xmax - geom.xmin;
    var height = geom.ymin - geom.ymax;

    var max = height;
    if ( width > height ) {
        max = width;
    }

    var margin = '-' + Math.floor(max/2) + 'px 0 0 -' + Math.floor(max/2) + 'px';

    query(".spotlight").addClass("spotlight-active").style({
      width: max + "px",
      height: max + "px",
      margin: margin
    });
    spotlight.remove();
  });
}

Finally, add logic to remove the spotlight when the map's extent changes.

geocoder.on("clear", removeSpotlight);

function removeSpotlight() {
  query(".spotlight").removeClass("spotlight-active");
  map.infoWindow.hide();
  map.graphics.clear();
}

After adding the code above, the selected result has a spotlight effect:

Putting it all together

Complete spotlight example:

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
    <title></title>
    <link rel="stylesheet" href="https://js.arcgis.com/3.46/esri/css/esri.css">
    <style>
      html, body, #map {
        height: 100%;
        width: 100%;
        margin: 0;
        padding: 0;
      }
      #search {
        display: block;
        position: absolute;
        z-index: 3;
        top: 20px;
        left: 75px;
      }
      .spotlight {
        z-index:-1;
        position:absolute;
        left:50%;
        top:50%;
        border-radius:50%;
        opacity:0;
        box-shadow:
        inset rgba(0,0,0,0.25) 0px 0px 20px 20px,
        rgba(0,0,0,0.25) 0px 0px 0px 1000px;
        transition:all 1000ms;
        -moz-transition:all 1000ms;
        -webkit-transition:all 1000ms;
      }
      .spotlight-active {
        z-index:2;
        opacity:1;
      }
    </style>

    <script src="https://js.arcgis.com/3.46/"></script>
    <script>
      require([
        "esri/map",
        "esri/dijit/Geocoder",
        "esri/graphic",
        "esri/symbols/SimpleMarkerSymbol",
        "esri/geometry/screenUtils",
        "dojo/dom",
        "dojo/dom-construct",
        "dojo/query",
        "dojo/_base/Color"
      ], function(Map, Geocoder, Graphic, SimpleMarkerSymbol, screenUtils, dom, domConstruct, query, Color) {
        // create a map and instance of the geocoder widget here
        var map = new Map("map", {
          basemap: "topo-vector",
          center: [ -100, 40 ],
          zoom: 10
        });
        var geocoder =  new Geocoder({
          arcgisGeocoder: {
            placeholder: "Find a place"
          },
          autoComplete: true,
          map: map
        }, dom.byId("search"));

        map.on("load", enableSpotlight);

        geocoder.on("select", showLocation);
        geocoder.on("clear", removeSpotlight);

        function showLocation(evt) {
          map.graphics.clear();
          var point = evt.result.feature.geometry;
          var symbol = new SimpleMarkerSymbol().setStyle(
            SimpleMarkerSymbol.STYLE_SQUARE).setColor(
            new Color([255,0,0,0.5])
          );
          var graphic = new Graphic(point, symbol);
          map.graphics.add(graphic);

          map.infoWindow.setTitle("Search Result");
          map.infoWindow.setContent(evt.result.name);
          map.infoWindow.show(evt.result.feature.geometry);

          var spotlight = map.on("extent-change", function(extentChange) {
            var geom = screenUtils.toScreenGeometry(map.extent, map.width, map.height, extentChange.extent);
            var width = geom.xmax - geom.xmin;
            var height = geom.ymin - geom.ymax;

            var max = height;
            if ( width > height ) {
                max = width;
            }

            var margin = '-' + Math.floor(max/2) + 'px 0 0 -' + Math.floor(max/2) + 'px';

            query(".spotlight").addClass("spotlight-active").style({
              width: max + "px",
              height: max + "px",
              margin: margin
            });
            spotlight.remove();
          });
        }

        function enableSpotlight() {
          var html = "<div id='spotlight' class='spotlight'></div>"
          domConstruct.place(html, dom.byId("map_container"), "first");
        }

        function removeSpotlight() {
          query(".spotlight").removeClass("spotlight-active");
          map.infoWindow.hide();
          map.graphics.clear();
        }
      });
    </script>
  </head>
  <body class="soria">
    <div id="search"></div>
    <div id="map"></div>
  </body>
</html>

Bonus: Use a custom geocoder

The Geocoder widget allows you to specify a custom geocoder to use along with or in place of the default geocoder. Use arcgisGeocoder: false and the geocoders constructor option to specify your own geocoding service:
```
var geocoder = new Geocoder({
  arcgisGeocoder: false,
  geocoders: [ {
    url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Locators/SanDiego/GeocodeServer",
    name: "San Diego Sample Geocoder",
    placeholder: "Locate",
    outFields: "*"
  }],
  map: map
}, dom.byId("search"));
```
Additional Geocoder samples are available in the Geocoding category of the samples section of this site.

	Site wide shortcuts
`?`	Bring up this help dialog
`esc`	Dismiss this help dialog
`gh`	Go to Home
`gg`	Go to Guide
`ga`	Go to API Reference
`gs`	Go to Sample Code
`gt`	Scroll to top of page
`spacebar`	Scroll page down
`shift spacebar`	Scroll page up
`gb`	Scroll to bottom of page

Introduction to the Geocoder widget

Require modules

Create an element in your HTML document to house the widget.

Specify a style to position the widget over the map and make the map fill the entire page.

Instantiate the widget

Enable auto-complete

Show selected result on the map

Using Placeholder Text

Create a spotlight effect

Putting it all together

Bonus: Use a custom geocoder

Keyboard shortcuts