Controls Overview
The maps displayed through the Maps JavaScript 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 application. Alternatively, you can do nothing and let the Maps JavaScript API handle all control behavior.
The following map shows the default set of controls displayed by the Maps JavaScript API:
Below is a list of the full set of controls you can use in your maps:
- The Zoom control displays "+" and "-" buttons for changing the zoom level of the map. This control appears by default in the bottom right corner of the map.
- The Camera control features both zoom and pan controls, and is displayed by default in place of the zoom control when using the beta channel.
- The Map Type control is available in a drop-down
or horizontal button bar style, allowing the user to choose a map type
(
ROADMAP
,SATELLITE
,HYBRID
, orTERRAIN
). This control appears by default in the top left 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 near the bottom right of the map.
- The Rotate control provides a combination of tilt and rotate options for maps containing oblique imagery. This control appears by default near the bottom right of the map. See 45° imagery for more information.
- The Scale control displays a map scale element. This control is disabled by default.
- The Fullscreen control offers the option to open the map in fullscreen mode. This control is enabled by default on desktop and mobile devices. Note: iOS doesn't support the fullscreen feature. The fullscreen control is therefore not visible on iOS devices.
- The Keyboard shortcuts control displays a list of keyboard shortcuts for interacting with the map.
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, all the controls disappear if the map is too small (200x200px). You can override this behavior by explicitly setting the control to be visible. See Adding Controls to the Map.
The behavior and appearance of the controls is the same across mobile and desktop devices, except for the fullscreen control (see the behavior described in the list of controls).
Additionally, keyboard handling is on by default on all devices.
Disable the Default UI
You may want to turn off the API's default UI buttons entirely. To do so,
set the map's disableDefaultUI
property (within the
MapOptions
object) to true
. This property
disables any UI control buttons from the Maps JavaScript API. It
does not, however, affect mouse gestures or keyboard shortcuts on the base
map, which are controlled by the gestureHandling
and
keyboardShortcuts
properties respectively.
The following code disables the UI buttons:
TypeScript
function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 4, center: { lat: -33, lng: 151 }, disableDefaultUI: true, } ); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 4, center: { lat: -33, lng: 151 }, disableDefaultUI: true, }); } window.initMap = initMap;
Try Sample
Add Controls to the Map
You may want 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 want 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 won't 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:
{ zoomControl: boolean, cameraControl: boolean, mapTypeControl: boolean, scaleControl: boolean, streetViewControl: boolean, rotateControl: boolean, fullscreenControl: boolean }
By default, all the controls disappear if the map is smaller than 200x200px.
You can override this behavior by explicitly setting the control to be
visible. For example, the following table shows whether the zoom control is
visible or not, based on the map size and the setting of the
zoomControl
field:
Map size | zoomControl |
Visible? |
---|---|---|
Any | false |
No |
Any | true |
Yes |
>= 200x200px | undefined |
Yes |
< 200x200px | undefined |
No |
The following example sets the map to hide the Zoom control and display the Scale control. Note that we don't explicitly disable the default UI, so these modifications are additive to the default UI behavior.
TypeScript
function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 4, center: { lat: -33, lng: 151 }, zoomControl: false, scaleControl: true, } ); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 4, center: { lat: -33, lng: 151 }, zoomControl: false, scaleControl: true, }); } window.initMap = initMap;
Try Sample
Control Options
Several controls are configurable, allowing you to alter their behavior or change their appearance. The Map Type control, for example, may appear as a horizontal bar or a drop-down menu.
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 Map Type control are indicated in the
mapTypeControlOptions
field. The Map Type 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 using a drop-down 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 Map Type control
to exhibit the DROPDOWN_MENU
style, use the following code within
the MapOptions
object:
... mapTypeControl: true, mapTypeControlOptions: { style: google.maps.MapTypeControlStyle.DROPDOWN_MENU } ...
The following example demonstrates how to change the default position and style of controls.
TypeScript
// You can set control options to change the default position or style of many // of the map controls. function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 4, center: { lat: -33, lng: 151 }, mapTypeControl: true, mapTypeControlOptions: { style: google.maps.MapTypeControlStyle.DROPDOWN_MENU, mapTypeIds: ["roadmap", "terrain"], }, } ); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// You can set control options to change the default position or style of many // of the map controls. function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 4, center: { lat: -33, lng: 151 }, mapTypeControl: true, mapTypeControlOptions: { style: google.maps.MapTypeControlStyle.DROPDOWN_MENU, mapTypeIds: ["roadmap", "terrain"], }, }); } window.initMap = initMap;
Try Sample
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.
Modify 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:
zoomControl
enables/disables the Zoom control. By default, this control is visible and appears near the bottom right of the map. ThezoomControlOptions
field additionally specifies theZoomControlOptions
to use for this control.cameraControl
enables/disables the camera control. This control is visible by default on maps using the beta channel. ThecameraControlOptions
field additionally specifies theCameraControlOptions
to use for this control.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 left corner of the map. ThemapTypeControlOptions
field additionally specifies theMapTypeControlOptions
to use for this control.streetViewControl
enables/disables the Pegman control that lets the user activate a Street View panorama. By default, this control is visible and appears near the bottom right of the map. ThestreetViewControlOptions
field additionally specifies theStreetViewControlOptions
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 presence 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'srotateControlOptions
to specify theRotateControlOptions
to use. You cannot make the control appear if no 45° imagery is available.scaleControl
enables/disables the Scale control that provides a map scale. By default, this control is not visible. When enabled, it will always appear in the bottom right corner of the map. ThescaleControlOptions
additionally specifies theScaleControlOptions
to use for this control.fullscreenControl
enables/disables the control that opens the map in fullscreen mode. By default, this control is enabled by default on desktop and Android devices. When enabled, the control appears near the top right of the map. ThefullscreenControlOptions
additionally specifies theFullscreenControlOptions
to use for this control.
Note that you may specify options for controls you initially disable.
Control Positioning
Most of the control options contain 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 lay out 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 anyTOP_LEFT
elements.RIGHT_TOP
indicates that the control should be placed along the top right of the map, but below anyTOP_RIGHT
elements.LEFT_CENTER
indicates that the control should be placed along the left side of the map, centered between theTOP_LEFT
andBOTTOM_LEFT
positions.RIGHT_CENTER
indicates that the control should be placed along the right side of the map, centered between theTOP_RIGHT
andBOTTOM_RIGHT
positions.LEFT_BOTTOM
indicates that the control should be placed along the bottom left of the map, but above anyBOTTOM_LEFT
elements.RIGHT_BOTTOM
indicates that the control should be placed along the bottom right of the map, but above anyBOTTOM_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.
TypeScript
function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 12, center: { lat: -28.643387, lng: 153.612224 }, mapTypeControl: true, mapTypeControlOptions: { style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR, position: google.maps.ControlPosition.TOP_CENTER, }, zoomControl: true, zoomControlOptions: { position: google.maps.ControlPosition.LEFT_CENTER, }, scaleControl: true, streetViewControl: true, streetViewControlOptions: { position: google.maps.ControlPosition.LEFT_TOP, }, fullscreenControl: true, } ); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 12, center: { lat: -28.643387, lng: 153.612224 }, mapTypeControl: true, mapTypeControlOptions: { style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR, position: google.maps.ControlPosition.TOP_CENTER, }, zoomControl: true, zoomControlOptions: { position: google.maps.ControlPosition.LEFT_CENTER, }, scaleControl: true, streetViewControl: true, streetViewControlOptions: { position: google.maps.ControlPosition.LEFT_TOP, }, fullscreenControl: true, }); } window.initMap = initMap;
Try Sample
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 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 practice:
- Define appropriate CSS for the control element(s) to display.
- Handle interaction with the user or the map through event handlers for
either map property changes or user events (for example,
'click'
events). - Create a
<div>
element to hold the control and add this element to theMap
'scontrols
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 a function to create a button element that pans the map to be centered on Chicago.
function createCenterControl(map) { const controlButton = document.createElement("button"); // Set CSS for the control. controlButton.style.backgroundColor = "#fff"; controlButton.style.border = "2px solid #fff"; controlButton.style.borderRadius = "3px"; controlButton.style.boxShadow = "0 2px 6px rgba(0,0,0,.3)"; controlButton.style.color = "rgb(25,25,25)"; controlButton.style.cursor = "pointer"; controlButton.style.fontFamily = "Roboto,Arial,sans-serif"; controlButton.style.fontSize = "16px"; controlButton.style.lineHeight = "38px"; controlButton.style.margin = "8px 0 22px"; controlButton.style.padding = "0 5px"; controlButton.style.textAlign = "center"; controlButton.textContent = "Center Map"; controlButton.title = "Click to recenter the map"; controlButton.type = "button"; // Setup the click event listeners: simply set the map to Chicago. controlButton.addEventListener("click", () => { map.setCenter(chicago); }); return controlButton; }
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, use addEventListener()
, which handles 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: set the map to center on Chicago var chicago = {lat: 41.850, lng: -87.650}; controlButton.addEventListener('click', () => { map.setCenter(chicago); });
Making Custom Controls Accessible
To ensure that controls receive keyboard events and appear correctly to screen readers:
- Always use native HTML elements for buttons, form elements, and labels. Only use a DIV element as a container to hold native controls; never repurpose a DIV as an interactive UI element.
- Use the
label
element,title
attribute, oraria-label
attribute where appropriate, to provide information about a UI element.
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.ControlPosition
s. 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'), mapOptions); // Create a DIV to attach the control UI to the Map. const centerControlDiv = document.createElement("div"); // Create the control. This code calls a function that // creates a new instance of a button control. const centerControl = createCenterControl(map); // Append the control to the DIV. centerControlDiv.appendChild(centerControl); // 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_CENTER].push(centerControlDiv);
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:
TypeScript
let map: google.maps.Map; const chicago = { lat: 41.85, lng: -87.65 }; /** * Creates a control that recenters the map on Chicago. */ function createCenterControl(map) { const controlButton = document.createElement('button'); // Set CSS for the control. controlButton.style.backgroundColor = '#fff'; controlButton.style.border = '2px solid #fff'; controlButton.style.borderRadius = '3px'; controlButton.style.boxShadow = '0 2px 6px rgba(0,0,0,.3)'; controlButton.style.color = 'rgb(25,25,25)'; controlButton.style.cursor = 'pointer'; controlButton.style.fontFamily = 'Roboto,Arial,sans-serif'; controlButton.style.fontSize = '16px'; controlButton.style.lineHeight = '38px'; controlButton.style.margin = '8px 0 22px'; controlButton.style.padding = '0 5px'; controlButton.style.textAlign = 'center'; controlButton.textContent = 'Center Map'; controlButton.title = 'Click to recenter the map'; controlButton.type = 'button'; // Setup the click event listeners: simply set the map to Chicago. controlButton.addEventListener('click', () => { map.setCenter(chicago); }); return controlButton; } function initMap() { map = new google.maps.Map(document.getElementById('map') as HTMLElement, { zoom: 12, center: chicago, }); // Create the DIV to hold the control. const centerControlDiv = document.createElement('div'); // Create the control. const centerControl = createCenterControl(map); // Append the control to the DIV. centerControlDiv.appendChild(centerControl); map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
let map; const chicago = { lat: 41.85, lng: -87.65 }; /** * Creates a control that recenters the map on Chicago. */ function createCenterControl(map) { const controlButton = document.createElement("button"); // Set CSS for the control. controlButton.style.backgroundColor = "#fff"; controlButton.style.border = "2px solid #fff"; controlButton.style.borderRadius = "3px"; controlButton.style.boxShadow = "0 2px 6px rgba(0,0,0,.3)"; controlButton.style.color = "rgb(25,25,25)"; controlButton.style.cursor = "pointer"; controlButton.style.fontFamily = "Roboto,Arial,sans-serif"; controlButton.style.fontSize = "16px"; controlButton.style.lineHeight = "38px"; controlButton.style.margin = "8px 0 22px"; controlButton.style.padding = "0 5px"; controlButton.style.textAlign = "center"; controlButton.textContent = "Center Map"; controlButton.title = "Click to recenter the map"; controlButton.type = "button"; // Setup the click event listeners: simply set the map to Chicago. controlButton.addEventListener("click", () => { map.setCenter(chicago); }); return controlButton; } function initMap() { map = new google.maps.Map(document.getElementById("map"), { zoom: 12, center: chicago, }); // Create the DIV to hold the control. const centerControlDiv = document.createElement("div"); // Create the control. const centerControl = createCenterControl(map); // Append the control to the DIV. centerControlDiv.appendChild(centerControl); map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv); } window.initMap = initMap;
Try Sample
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.
TypeScript
let map: google.maps.Map; const chicago: google.maps.LatLngLiteral = { lat: 41.85, lng: -87.65 }; /** * The CenterControl adds a control to the map that recenters the map on * Chicago. */ class CenterControl { private map_: google.maps.Map; private center_: google.maps.LatLng; constructor( controlDiv: HTMLElement, map: google.maps.Map, center: google.maps.LatLngLiteral ) { this.map_ = map; // Set the center property upon construction this.center_ = new google.maps.LatLng(center); controlDiv.style.clear = "both"; // Set CSS for the control border const goCenterUI = document.createElement("button"); goCenterUI.id = "goCenterUI"; goCenterUI.title = "Click to recenter the map"; controlDiv.appendChild(goCenterUI); // Set CSS for the control interior const goCenterText = document.createElement("div"); goCenterText.id = "goCenterText"; goCenterText.innerHTML = "Center Map"; goCenterUI.appendChild(goCenterText); // Set CSS for the setCenter control border const setCenterUI = document.createElement("button"); setCenterUI.id = "setCenterUI"; setCenterUI.title = "Click to change the center of the map"; controlDiv.appendChild(setCenterUI); // Set CSS for the control interior const setCenterText = document.createElement("div"); setCenterText.id = "setCenterText"; setCenterText.innerHTML = "Set Center"; setCenterUI.appendChild(setCenterText); // Set up the click event listener for 'Center Map': Set the center of // the map // to the current center of the control. goCenterUI.addEventListener("click", () => { const currentCenter = this.center_; this.map_.setCenter(currentCenter); }); // Set up the click event listener for 'Set Center': Set the center of // the control to the current center of the map. setCenterUI.addEventListener("click", () => { const newCenter = this.map_.getCenter()!; if (newCenter) { this.center_ = newCenter; } }); } } function initMap(): void { map = new google.maps.Map(document.getElementById("map") as HTMLElement, { zoom: 12, center: chicago, }); // Create the DIV to hold the control and call the CenterControl() // constructor passing in this DIV. const centerControlDiv = document.createElement("div"); const control = new CenterControl(centerControlDiv, map, chicago); // @ts-ignore centerControlDiv.index = 1; centerControlDiv.style.paddingTop = "10px"; map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
let map; const chicago = { lat: 41.85, lng: -87.65 }; /** * The CenterControl adds a control to the map that recenters the map on * Chicago. */ class CenterControl { map_; center_; constructor(controlDiv, map, center) { this.map_ = map; // Set the center property upon construction this.center_ = new google.maps.LatLng(center); controlDiv.style.clear = "both"; // Set CSS for the control border const goCenterUI = document.createElement("button"); goCenterUI.id = "goCenterUI"; goCenterUI.title = "Click to recenter the map"; controlDiv.appendChild(goCenterUI); // Set CSS for the control interior const goCenterText = document.createElement("div"); goCenterText.id = "goCenterText"; goCenterText.innerHTML = "Center Map"; goCenterUI.appendChild(goCenterText); // Set CSS for the setCenter control border const setCenterUI = document.createElement("button"); setCenterUI.id = "setCenterUI"; setCenterUI.title = "Click to change the center of the map"; controlDiv.appendChild(setCenterUI); // Set CSS for the control interior const setCenterText = document.createElement("div"); setCenterText.id = "setCenterText"; setCenterText.innerHTML = "Set Center"; setCenterUI.appendChild(setCenterText); // Set up the click event listener for 'Center Map': Set the center of // the map // to the current center of the control. goCenterUI.addEventListener("click", () => { const currentCenter = this.center_; this.map_.setCenter(currentCenter); }); // Set up the click event listener for 'Set Center': Set the center of // the control to the current center of the map. setCenterUI.addEventListener("click", () => { const newCenter = this.map_.getCenter(); if (newCenter) { this.center_ = newCenter; } }); } } function initMap() { map = new google.maps.Map(document.getElementById("map"), { zoom: 12, center: chicago, }); // Create the DIV to hold the control and call the CenterControl() // constructor passing in this DIV. const centerControlDiv = document.createElement("div"); const control = new CenterControl(centerControlDiv, map, chicago); // @ts-ignore centerControlDiv.index = 1; centerControlDiv.style.paddingTop = "10px"; map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv); } window.initMap = initMap;