Maps API V3 Controls

Controls Overview

The maps on Google Maps contain UI elements for allowing user interaction through 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 Navigation control displays a large pan/zoom control as used on Google Maps. This control appears by default in the top left corner of the map.
• 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.

You don't access or modify 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

Rather than specifying and setting up individual controls, you may simply wish to specify that your map exhibit the look and feel of the Google Maps interface, (including any new features or controls that get added in the future). To get this behavior, you need do nothing. Your map will show up with default controls.

The Default Control Set

The Maps API provides the following default controls:

Control	Large Screens	Small Screens	iPhone	Android
Navigation	Large Pan/Zoom for sizes larger than 400x350px	Small Mini-Zoom for sizes smaller than 400x350px	Not present	"Android" control
MapType	Horizontal Bar for screens larger than 320px wide	Dropdown for screens smaller than 320px wide	Same as Large/Small Screens	Same as Large/Small Screens
Scale	Not present	Not present	Not present	Not present

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 Map options 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 myOptions = {
    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"),
       myOptions);                          
}

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 Map options object's fields, which you set to true to make them visible or set to false to hide them:

{
  navigationControl: boolean,
  mapTypeControl: boolean,
  scaleControl: boolean
}

Note that the Maps API V3 does not currently allow you to dynamically add or remove controls. These must be set upon creation of the map through a Map options object.

The following example sets the map to hide the navigation control 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 myOptions = {
    zoom: 4,
    center: new google.maps.LatLng(-33, 151),
    navigationControl: false,
    scaleControl: true,
    mapTypeId: google.maps.MapTypeId.ROADMAP
  }
  var map = new google.maps.Map(document.getElementById("map_canvas"),
                                  myOptions);
}

View example (control-simple.html)

Control Options

Several controls are configurable, allowing you to alter their behavior or change their appearance. The Navigation control, for example, may display as either a large control with a full zoom control and panning controls as shown on Google Maps, or as a smaller, mini-zoom control for smaller devices.

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 Navigation control are indicated in the navigationControlOptions field.

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

• google.maps.NavigationControlStyle.SMALL displays a mini-zoom control, consisting of only + and - buttons. This style is appropriate for mobile devices.
• google.maps.NavigationControlStyle.ZOOM_PAN displays the standard zoom slider control with a panning control, as on Google Maps.
• google.maps.NavigationControlStyle.ANDROID displays the small zoom control as used on the native Maps application on Android devices.
• google.maps.NavigationControlStyle.DEFAULT picks an appropriate navigation 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 Navigation control to exhibit the SMALL style, use the following code within the MapOptions object:

  ...
  navigationControl: true,
  navigationControlOptions: {
    style: google.maps.NavigationControlStyle.SMALL
  }
  ...

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

function initialize() {
  var myOptions = {
    zoom: 4,
    center: new google.maps.LatLng(-33, 151),
    mapTypeControl: true,
    mapTypeControlOptions: {style: google.maps.MapTypeControlStyle.DROPDOWN_MENU},
    navigationControl: true,
    navigationControlOptions: {style: google.maps.NavigationControlStyle.SMALL},
    mapTypeId: google.maps.MapTypeId.ROADMAP      
  }
  var map = new google.maps.Map(document.getElementById("map_canvas"),
                                  myOptions);                          
}

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.
• navigationControl enables/disables the Navigation control that provides a pan/zoom control. By default, this control is visible and appears in the top left corner of the map. The navigationControlOptions field additionally specifies the NavigationControlOptions 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 appears in the bottom left corner of the map. The scaleControlOptions additionally specifies the ScaleControlOptions 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 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.
• BOTTOM 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.
• LEFT indicates that the control should be placed along the left side of the map, below any elements placed with TOP_LEFT positioning, with any sub-elements of the control "flowing" down towards the bottom.
• RIGHT indicates that the control should be placed along the right side of the map, below any elements placed with TOP_RIGHT positioning, with any sub-elements of the control "flowing" down towards the bottom.

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 myOptions = {
    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
    },
    navigationControl: true,
    navigationControlOptions: {
        style: google.maps.NavigationControlStyle.ZOOM_PAN,
        position: google.maps.ControlPosition.TOP_RIGHT
    },
    scaleControl: true,
    scaleControlOptions: {
        position: google.maps.ControlPosition.TOP_LEFT
    }     
  }
  var map = new google.maps.Map(document.getElementById("map_canvas"),
      myOptions);                          
}

View example (control-positioning.html)