` 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 `

` element to hold the control and add this element to the `Map`'s `controls` property. Each of these concerns is discussed below. ### Draw 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 `

` 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 examples show adding a custom control using both declarative HTML and programmatic methods. #### Declarative CSS The following CSS styles provide an appearance that's consistent with the default controls. Use these styles with both of the examples below: ```css .streetview-toggle-button { align-items: center; background: white; border: none; border-radius: 2px; box-shadow: 0 1px 4px -1px rgba(0, 0, 0, 0.3); color: rgb(86, 86, 86); cursor: pointer; display: flex; font-family: Roboto, Arial, sans-serif; font-size: 18px; font-weight: 400; height: 40px; justify-content: center; margin: 10px 0; padding: 0 17px; } .streetview-toggle-button:hover { background: #f4f4f4; color: #000; } ``` #### Declarative HTML These code snippets show how to create a custom control declaratively. In the HTML, a DIV with the ID `container` is used to position the control; this is nested within the `gmp-map` element and the button is added to the DIV. The `slot` attribute is set to `control-inline-start-block-start` to position the control in the top left corner of the map. ```html

``` In the JavaScript, `getElementById()` is used to find the DIV and button, an event listener is added to the button, and the button is appended to the DIV. ```javascript // Create a DIV to attach the control UI to the Map. const container = document.getElementById("container"); // Get the control button from the HTML page. const controlButton = document.getElementById("streetview-toggle-button"); // Add a click event listener. controlButton.addEventListener("click", () => { window.alert("You clicked the button!"); }); // Add the control to the DIV. container.append(controlButton); ``` #### Programmatic JavaScript This code snippet demonstrates programmatically creating a button control. The CSS styles are defined above. ```javascript // Create a DIV to attach the control UI to the Map. const container = document.getElementById("container"); // Position the control in the top left corner of the map. container.slot = "control-block-start-inline-start"; // Create the control. const controlButton = document.createElement("button"); controlButton.classList.add("streetview-toggle-button"); controlButton.textContent = "Click this button"; controlButton.type = "button"; // Add a click event listener. controlButton.addEventListener("click", () => { window.alert("You clicked the button!"); }); // Add the control to the DIV. container.append(controlButton); ``` ### Handle 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](https://en.wikipedia.org/wiki/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. ```javascript // 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); }); ``` ### Make 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, or `aria-label` attribute where appropriate, to provide information about a UI element. ### Position Custom Controls Use the `slot` attribute to position custom controls, specifying the needed control position. For information on these positions, see [Control Positioning](https://developers.google.com/maps/documentation/javascript/controls.md.txt#ControlPositioning) 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 following code creates a new custom control (its constructor is not shown) and adds it to the map in the ` BLOCK_START_INLINE_END` position (top-right in LTR context). ```javascript // 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); // Push the control to the `BLOCK_START_INLINE_END` position. innerMap.controls[google.maps.ControlPosition.BLOCK_START_INLINE_END].push(centerControlDiv); ``` To set position for a custom control declaratively, set the `slot` attribute in the HTML: ```html

``` ### 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 ```typescript const chicago = { lat: 41.85, lng: -87.65 }; // Get the gmp-map element const mapElement = document.querySelector('gmp-map')!; async function init() { (await google.maps.importLibrary('maps')) as typeof google.maps; // Get the inner map. const innerMap = mapElement.innerMap; // Get the button element from the HTML const centerButton = document.getElementById( 'btnCenterMap' ) as HTMLButtonElement; // Move the event listener here centerButton.addEventListener('click', () => { innerMap.setCenter(chicago); }); } void init(); ``` ### JavaScript ```javascript const chicago = { lat: 41.85, lng: -87.65 }; // Get the gmp-map element const mapElement = document.querySelector('gmp-map'); async function init() { await google.maps.importLibrary('maps'); // Get the inner map. const innerMap = mapElement.innerMap; // Get the button element from the HTML const centerButton = document.getElementById('btnCenterMap'); // Move the event listener here centerButton.addEventListener('click', () => { innerMap.setCenter(chicago); }); } void init(); ``` [View example](https://developers.google.com/maps/documentation/javascript/examples/control-custom.md.txt) ### Try Sample [JSFiddle.net](https://jsfiddle.net/gh/get/library/pure/googlemaps-samples/js-api-samples/tree/main/dist/samples/control-custom/jsfiddle) ### Add 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 ```typescript let innerMap: google.maps.Map; const mapElement = document.querySelector('gmp-map')!; let center: google.maps.LatLngLiteral | google.maps.LatLng = { lat: 41.85, lng: -87.65, }; async function init() { await google.maps.importLibrary('maps'); innerMap = mapElement.innerMap; // Get the button UI elements. const centerMapButton = document.getElementById( 'btnCenterMap' ) as HTMLInputElement; const setCenterButton = document.getElementById( 'btnSetCenter' ) as HTMLInputElement; // Set up the click event listener for the 'Center Map' button. Set the map // to the currently stored center. centerMapButton.addEventListener('click', () => { const currentCenter = center; innerMap.setCenter(currentCenter); }); // Set up the click event listener for 'Set Center': Set the center of // the control to the current center of the map. setCenterButton.addEventListener('click', () => { const newCenter = innerMap.getCenter(); if (newCenter) { center = newCenter; } }); } void init(); ``` ### JavaScript ```javascript let innerMap; const mapElement = document.querySelector('gmp-map'); let center = { lat: 41.85, lng: -87.65, }; async function init() { await google.maps.importLibrary('maps'); innerMap = mapElement.innerMap; // Get the button UI elements. const centerMapButton = document.getElementById('btnCenterMap'); const setCenterButton = document.getElementById('btnSetCenter'); // Set up the click event listener for the 'Center Map' button. Set the map // to the currently stored center. centerMapButton.addEventListener('click', () => { const currentCenter = center; innerMap.setCenter(currentCenter); }); // Set up the click event listener for 'Set Center': Set the center of // the control to the current center of the map. setCenterButton.addEventListener('click', () => { const newCenter = innerMap.getCenter(); if (newCenter) { center = newCenter; } }); } void init(); ``` [View example](https://developers.google.com/maps/documentation/javascript/examples/control-custom-state.md.txt) ### Try Sample [JSFiddle.net](https://jsfiddle.net/gh/get/library/pure/googlemaps-samples/js-api-samples/tree/main/dist/samples/control-custom-state/jsfiddle)