1. Map Controls Overview
2. The Default UI
   1. The Default Control Set
   2. Disabling the Default UI
3. Adding Controls to the Map
4. Control Options
   1. Modifying Control Presentation
   2. Control Positioning
5. Custom Map Controls
   1. Positioning Custom Map Controls
   2. Drawing Custom Map Controls
   3. Handling Events from Custom Map Controls
   4. A Custom Map Control Example
   5. Adding State to Map Controls

Controls Overview

The maps displayed through the Google Maps API contain UI elements to allow user interaction with the map. These elements are known as controls and you can include variations of these controls in your Google Maps API application. Alternatively, you can do nothing and let the Google Maps API handle all control behavior.

The Maps API comes with a handful of built-in controls you can use in your maps:

• The Zoom control displays a slider (for large maps) or small "+/-" buttons (for small maps) to control the zoom level of the map. This control appears by default in the top left corner of the map on non-touch devices or in the bottom left corner on touch devices.
• The Pan control displays buttons for panning the map. This control appears by default in the top left corner of the map on non-touch devices. The Pan control also allows you to rotate 45° imagery, if available.
• The Scale control displays a map scale element. This control is not enabled by default.
• The MapType control lets the user toggle between map types (such as ROADMAP and SATELLITE). This control appears by default in the top right corner of the map.
• The Street View control contains a Pegman icon which can be dragged onto the map to enable Street View. This control appears by default in the top left corner of the map.
• The Rotate control contains a small circular icon which allows you to rotate maps containing oblique imagery. This control appears by default in the top left corner of the map. (See 45° Imagery for more information.)
• The Overview Map control displays a thumbnail overview map reflecting the current map viewport within a wider area. This control appears by default in the bottom right corner of the map, and is by default shown in its collapsed state.

You don't access or modify these map controls directly. Instead, you modify the map's MapOptions fields which affect the visibility and presentation of controls. You can adjust control presentation upon instantiating your map (with appropriate MapOptions) or modify a map dynamically by calling setOptions() to change the map's options.

Not all of these controls are enabled by default. To learn about default UI behavior (and how to modify such behavior), see The Default UI below.

The Default UI

By default, your map and the associated map controls will match the standard look and feel of the Google Maps interface. If you would like to enable the new Google Maps look and feel, you can enable the VisualRefresh property.

The Default Control Set

The Maps API provides the following default controls:

Additionally, keyboard handling is on by default on all devices.

Disabling the Default UI

You may instead wish to turn off the API's default UI settings. To do so, set the Map's disableDefaultUI property (within the MapOptions object) to true. This property disables any automatic UI behavior from the Google Maps API.

The following code disables the default UI entirely:

function initialize() {
  var mapOptions = {
    zoom: 4,
    center: new google.maps.LatLng(-33, 151),
    disableDefaultUI: true,
    mapTypeId: google.maps.MapTypeId.ROADMAP
  }
  var map = new google.maps.Map(document.getElementById("map-canvas"),
       mapOptions);
}

View example (control-disableUI.html)

Adding Controls to the Map

You may wish to tailor your interface by removing, adding, or modifying UI behavior or controls and ensure that future updates don't alter this behavior. If you wish to only add or modify existing behavior, you need to ensure that the control is explicitly added to your application.

Some controls appear on the map by default while others will not appear unless you specifically request them. Adding or removing controls from the map is specified in the following MapOptions object's fields, which you set to true to make them visible or set to false to hide them:

{
  panControl: boolean,
  zoomControl: boolean,
  mapTypeControl: boolean,
  scaleControl: boolean,
  streetViewControl: boolean,
  overviewMapControl: boolean
}

The following example sets the map to hide the navigation (Zoom and Pan) controls and display the scale control. Note that we do not explicitly disable the default UI, so these modifications are additive to the default UI behavior.

function initialize() {
  var mapOptions = {
    zoom: 4,
    center: new google.maps.LatLng(-33, 151),
    panControl: false,
    zoomControl: false,
    scaleControl: true,
    mapTypeId: google.maps.MapTypeId.ROADMAP
  }
  var map = new google.maps.Map(document.getElementById("map-canvas"),
        mapOptions);
}

View example (control-simple.html)

Control Options

Several controls are configurable, allowing you to alter their behavior or change their appearance. The Zoom control, for example, may display as either a large control with a full zoom control with slider, or as a smaller, mini-zoom control for smaller maps.

These controls are modified by altering appropriate control options fields within the MapOptions object upon creation of the map. For example, options for altering the Zoom control are indicated in the zoomControlOptions field.

The Zoom control may appear in one of the following style options:

• google.maps.ZoomControlStyle.SMALL displays a mini-zoom control, consisting of only + and - buttons. This style is appropriate for small maps. On touch devices, this control displays as + and - buttons that are responsive to touch events.
• google.maps.ZoomControlStyle.LARGE displays the standard zoom slider control. On touch devices, this control displays as + and - buttons that are responsive to touch events.
• google.maps.ZoomControlStyle.DEFAULT picks an appropriate zoom control based on the map's size and the device on which the map is running.

The MapType control may appear in one of the following style options:

• google.maps.MapTypeControlStyle.HORIZONTAL_BAR displays the array of controls as buttons in a horizontal bar as is shown on Google Maps.
• google.maps.MapTypeControlStyle.DROPDOWN_MENU displays a single button control allowing you to select the map type via a dropdown menu.
• google.maps.MapTypeControlStyle.DEFAULT displays the "default" behavior, which depends on screen size and may change in future versions of the API

Note that if you do modify any control options, you should explicitly enable the control as well by setting the appropriate MapOptions value to true. For example, to set a Zoom control to exhibit the SMALL style, use the following code within the MapOptions object:

  ...
  zoomControl: true,
  zoomControlOptions: {
    style: google.maps.ZoomControlStyle.SMALL
  }
  ...

The following example sets a drop-down MapType control and specifies that the Zoom control use a small mini-zoom layout:

function initialize() {
  var mapOptions = {
    zoom: 4,
    center: new google.maps.LatLng(-33, 151),
    mapTypeControl: true,
    mapTypeControlOptions: {
      style: google.maps.MapTypeControlStyle.DROPDOWN_MENU
    },
    zoomControl: true,
    zoomControlOptions: {
      style: google.maps.ZoomControlStyle.SMALL
    },
    mapTypeId: google.maps.MapTypeId.ROADMAP
  }
  var map = new google.maps.Map(document.getElementById("map-canvas"),
      mapOptions);
}

View example (control-options.html)

Controls are typically configured upon creation of the map. However, you may alter the presentation of controls dynamically by calling the Map's setOptions() method, passing it new control options.

Modifying Controls

You specify a control's presentation when you create your map through fields within the map's MapOptions object. These fields are denoted below:

• mapTypeControl enables/disables the Map Type control that lets the user toggle between map types (such as Map and Satellite). By default, this control is visible and appears in the top right corner of the map. The mapTypeControlOptions field additionally specifies the MapTypeControlOptions to use for this control.
• panControl enables/disables the Pan control. By default, this control is visible and appears in the top left corner of the map. The panControlOptions field additionally specifies the PanControlOptions to use for this control.
• zoomControl enables/disables the Zoom control. By default, this control is visible and appears in the top left corner of the map. The zoomControlOptions field additionally specifies the ZoomControlOptions to use for this control.
• scaleControl enables/disables the Scale control that provides a simple map scale. By default, this control is not visible. When enabled, it will appear in the bottom left corner of a classic map, or the bottom right corner of a map with the Visual Refresh mode enabled. The scaleControlOptions additionally specifies the ScaleControlOptions to use for this control.
• rotateControl enables/disables the appearance of a Rotate control for controlling the orientation of 45° imagery. By default, the control's appearance is determined by the presence or absence of 45° imagery for the given map type at the current zoom and location. You may alter the control's behavior by setting the map's rotateControlOptions to specify the RotateControlOptions to use (though you cannot make the control appear if no 45° imagery is currently available).
• overviewMapControl enables/disables the Overview Map control. The Overview Map control may be either fully displayed (showing a thumbnail overview map) or collapsed in a minimized state. By default, the control is disabled and collapsed. The overviewMapControlOptions additionally specifies the OverviewMapControlOptions to use for this control.

Note that you may specify options for controls you initially disable.

Control Positioning

Each of these control options contains a position property (of type ControlPosition) which indicates where on the map to place the control. Positioning of these controls is not absolute; instead, the API will layout the controls intelligently by "flowing" them around existing map elements, or other controls, within given constraints (such as the map size).

Note: No guarantees can be made that controls may not overlap given complicated layouts, though the API will attempt to arrange them intelligently.

The following control positions are supported:

• TOP_CENTER indicates that the control should be placed along the top center of the map.
• TOP_LEFT indicates that the control should be placed along the top left of the map, with any sub-elements of the control "flowing" towards the top center.
• TOP_RIGHT indicates that the control should be placed along the top right of the map, with any sub-elements of the control "flowing" towards the top center.
• LEFT_TOP indicates that the control should be placed along the top left of the map, but below any TOP_LEFT elements.
• RIGHT_TOP indicates that the control should be placed along the top right of the map, but below any TOP_RIGHT elements.
• LEFT_CENTER indicates that the control should be placed along the left side of the map, centered between the TOP_LEFT and BOTTOM_LEFT positions.
• RIGHT_CENTER indicates that the control should be placed along the right side of the map, centered between the TOP_RIGHT and BOTTOM_RIGHT positions.
• LEFT_BOTTOM indicates that the control should be placed along the bottom left of the map, but above any BOTTOM_LEFT elements.
• RIGHT_BOTTOM indicates that the control should be placed along the bottom right of the map, but above any BOTTOM_RIGHT elements.
• BOTTOM_CENTER indicates that the control should be placed along the bottom center of the map.
• BOTTOM_LEFT indicates that the control should be placed along the bottom left of the map, with any sub-elements of the control "flowing" towards the bottom center.
• BOTTOM_RIGHT indicates that the control should be placed along the bottom right of the map, with any sub-elements of the control "flowing" towards the bottom center.

Note that these positions may coincide with positions of UI elements whose placements you may not modify (such as copyrights and the Google logo). In those cases, the controls will "flow" according to the logic noted for each position and appear as close as possible to their indicated position.

The following example shows a simple map with all controls enabled, in different positions.

function initialize() {
  var mapOptions = {
    zoom: 12,
    center: new google.maps.LatLng(-28.643387, 153.612224),
    mapTypeId: google.maps.MapTypeId.ROADMAP,
    mapTypeControl: true,
    mapTypeControlOptions: {
        style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
        position: google.maps.ControlPosition.BOTTOM_CENTER
    },
    panControl: true,
    panControlOptions: {
        position: google.maps.ControlPosition.TOP_RIGHT
    },
    zoomControl: true,
    zoomControlOptions: {
        style: google.maps.ZoomControlStyle.LARGE,
        position: google.maps.ControlPosition.LEFT_CENTER
    },
    scaleControl: true,
    scaleControlOptions: {
        position: google.maps.ControlPosition.TOP_LEFT
    },
    streetViewControl: true,
    streetViewControlOptions: {
        position: google.maps.ControlPosition.LEFT_TOP
    }
  }
  var map = new google.maps.Map(document.getElementById("map-canvas"),
      mapOptions);
}

View example (control-positioning.html)

Custom Controls

As well as modifying the style and position of existing API controls, you can create your own controls to handle interaction with the user. Controls are stationary widgets which float on top of a map at absolute positions, as opposed to overlays, which move with the underlying map. More fundamentally, a control is simply a <div> element which has an absolute position on the map, displays some UI to the user, and handles interaction with either the user or the map, usually through an event handler.

To create your own custom control, few "rules" are necessary. However, the following guidelines can act as best practices:

• Define appropriate CSS for the control element(s) todisplay.
• Handle interaction with the user or the map through event handlers for either map property changes or user events (e.g. 'click' events).
• Create a <div> element to hold the control and add this element to the Map's controls property.

Each of these concerns is discussed below.

Drawing Custom Controls

How you draw your control is up to you. Generally, we recommend that you place all of your control presentation within a single <div> element so that you can manipulate your control as one unit. We will use this design pattern in the samples shown below.

Designing attractive controls requires some knowledge of CSS and DOM structure. The following code shows how a simple control is created from a containing <div>, a <div> to hold the button outline, and another <div> to hold the button interior.

// Create a div to hold the control.
var controlDiv = document.createElement('div');

// Set CSS styles for the DIV containing the control
// Setting padding to 5 px will offset the control
// from the edge of the map.
controlDiv.style.padding = '5px';

// Set CSS for the control border.
var controlUI = document.createElement('div');
controlUI.style.backgroundColor = 'white';
controlUI.style.borderStyle = 'solid';
controlUI.style.borderWidth = '2px';
controlUI.style.cursor = 'pointer';
controlUI.style.textAlign = 'center';
controlUI.title = 'Click to set the map to Home';
controlDiv.appendChild(controlUI);

// Set CSS for the control interior.
var controlText = document.createElement('div');
controlText.style.fontFamily = 'Arial,sans-serif';
controlText.style.fontSize = '12px';
controlText.style.paddingLeft = '4px';
controlText.style.paddingRight = '4px';
controlText.innerHTML = '<strong>Home</strong>';
controlUI.appendChild(controlText);

Handling Events from Custom Controls

For a control to be useful, it must actually do something. What the control does is up to you. The control may respond to user input, or it may respond to changes in the Map's state.

For responding to user input, the Maps API provides a cross-browser event handling method addDomListener() which handles most of the browser's supported DOM events. The following code snippet adds a listener for the browser's 'click' event. Note that this event is received from the DOM, not from the map.

// Setup the click event listener: simply set the map to center on Chicago
var chicago = new google.maps.LatLng(41.850033, -87.6500523);

google.maps.event.addDomListener(outer, 'click', function() {
  map.setCenter(chicago)
});

Positioning Custom Controls

Custom controls are positioned on the map by placing them at appropriate positions within the Map object's controls property. This property contains an array of google.maps.ControlPositions. You add a custom control to the map by adding the Node (typically the <div>) to an appropriate ControlPosition. (For information on these positions, see Control Positioning above.)

Each ControlPosition stores an MVCArray of the controls displayed in that position. As a result, when controls are added or removed from the position, the API will update the controls accordingly.

The API places controls at each position by the order of an index property; controls with a lower index are placed first. For example, two custom controls at position BOTTOM_RIGHT will be laid out according to this index order, with lower index values taking precedence. By default, all custom controls are placed after placing any API default controls. You can override this behavior by setting a control's index property to be a negative value. Custom controls cannot be placed to the left of the logo or to the right of the copyrights.

The following code creates a new custom control (its constructor is not shown) and adds it to the map in the TOP_RIGHT position.

var map = new google.maps.Map(document.getElementById('map-canvas'), mapOptions);

// Construct your control in whatever manner is appropriate.
// Generally, your constructor will want access to the
// DIV on which you'll attach the control UI to the Map.
var controlDiv = document.createElement('div');
var myControl = new MyControl(controlDiv);

// We don't really need to set an index value here, but
// this would be how you do it. Note that we set this
// value as a property of the DIV itself.
controlDiv.index = 1;

// Add the control to the map at a designated control position
// by pushing it on the position's array. This code will
// implicitly add the control to the DOM, through the Map
// object. You should not attach the control manually.
map.controls[google.maps.ControlPosition.TOP_RIGHT].push(controlDiv);

A Custom Control Example

The following control is simple (though not particularly useful) and combines the patterns shown above. This control responds to DOM 'click' events by centering the map at a certain default location:

var map;
var chicago = new google.maps.LatLng(41.850033, -87.6500523);

/**
 * The HomeControl adds a control to the map that simply
 * returns the user to Chicago. This constructor takes
 * the control DIV as an argument.
 */

function HomeControl(controlDiv, map) {

  // Set CSS styles for the DIV containing the control
  // Setting padding to 5 px will offset the control
  // from the edge of the map.
  controlDiv.style.padding = '5px';

  // Set CSS for the control border.
  var controlUI = document.createElement('div');
  controlUI.style.backgroundColor = 'white';
  controlUI.style.borderStyle = 'solid';
  controlUI.style.borderWidth = '2px';
  controlUI.style.cursor = 'pointer';
  controlUI.style.textAlign = 'center';
  controlUI.title = 'Click to set the map to Home';
  controlDiv.appendChild(controlUI);

  // Set CSS for the control interior.
  var controlText = document.createElement('div');
  controlText.style.fontFamily = 'Arial,sans-serif';
  controlText.style.fontSize = '12px';
  controlText.style.paddingLeft = '4px';
  controlText.style.paddingRight = '4px';
  controlText.innerHTML = '<strong>Home</strong>';
  controlUI.appendChild(controlText);

  // Setup the click event listeners: simply set the map to Chicago.
  google.maps.event.addDomListener(controlUI, 'click', function() {
    map.setCenter(chicago)
  });
}

function initialize() {
  var mapDiv = document.getElementById('map-canvas');
  var mapOptions = {
    zoom: 12,
    center: chicago,
    mapTypeId: google.maps.MapTypeId.ROADMAP
  }
  map = new google.maps.Map(mapDiv, mapOptions);

  // Create the DIV to hold the control and call the HomeControl() constructor
  // passing in this DIV.
  var homeControlDiv = document.createElement('div');
  var homeControl = new HomeControl(homeControlDiv, map);

  homeControlDiv.index = 1;
  map.controls[google.maps.ControlPosition.TOP_RIGHT].push(homeControlDiv);
}

View example (control-custom.html)

Adding State to Controls

Controls may also store state. The following example is similar to that shown before, but the control contains an additional "Set Home" button which sets the control to exhibit a new home location. We do so by creating a home_ property within the control to store this state and provide getters and setters for that state.

var map;
var chicago = new google.maps.LatLng(41.850033, -87.6500523);

/**
 * The HomeControl adds a control to the map that
 * returns the user to the control's defined home.
 */

// Define a property to hold the Home state.
HomeControl.prototype.home_ = null;

// Define setters and getters for this property.
HomeControl.prototype.getHome = function() {
  return this.home_;
};

HomeControl.prototype.setHome = function(home) {
  this.home_ = home;
};

function HomeControl(map, div, home) {

  // Get the control DIV. We'll attach our control UI to this DIV.
  var controlDiv = div;

  // We set up a variable for the 'this' keyword since we're adding event
  // listeners later and 'this' will be out of scope.
  var control = this;

  // Set the home property upon construction.
  control.home_ = home;

  // Set CSS styles for the DIV containing the control. Setting padding to
  // 5 px will offset the control from the edge of the map.
  controlDiv.style.padding = '5px';

  // Set CSS for the control border.
  var goHomeUI = document.createElement('div');
  goHomeUI.title = 'Click to set the map to Home';
  controlDiv.appendChild(goHomeUI);

  // Set CSS for the control interior.
  var goHomeText = document.createElement('div');
  goHomeText.innerHTML = '<strong>Home</strong>';
  goHomeUI.appendChild(goHomeText);

  // Set CSS for the setHome control border.
  var setHomeUI = document.createElement('div');
  setHomeUI.title = 'Click to set Home to the current center';
  controlDiv.appendChild(setHomeUI);

  // Set CSS for the control interior.
  var setHomeText = document.createElement('div');
  setHomeText.innerHTML = '<strong>Set Home</strong>';
  setHomeUI.appendChild(setHomeText);

  // Setup the click event listener for Home:
  // simply set the map to the control's current home property.
  google.maps.event.addDomListener(goHomeUI, 'click', function() {
    var currentHome = control.getHome();
    map.setCenter(currentHome);
  });

  // Setup the click event listener for Set Home:
  // Set the control's home to the current Map center.
  google.maps.event.addDomListener(setHomeUI, 'click', function() {
    var newHome = map.getCenter();
    control.setHome(newHome);
  });
}

function initialize() {
  var mapDiv = document.getElementById('map-canvas');
  var mapOptions = {
    zoom: 12,
    center: chicago,
    mapTypeId: google.maps.MapTypeId.ROADMAP
  }
  map = new google.maps.Map(mapDiv, mapOptions);

  // Create the DIV to hold the control and call the HomeControl()
  // constructor passing in this DIV.
  var homeControlDiv = document.createElement('div');
  var homeControl = new HomeControl(map, homeControlDiv, chicago);

  homeControlDiv.index = 1;
  map.controls[google.maps.ControlPosition.TOP_RIGHT].push(homeControlDiv);
}

View example (control-custom-state.html)

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.