--- title: "Add a custom control declarative way | JavaScript maps SDK" description: "Add interactive custom controls to maps using declarative HTML." --- > For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL. # Add a custom control declarative way Declarative controls offer a simple way to add interactive UI elements to the map by using HTML attributes alone. Instead of instantiating controls through JavaScript, developers annotate DOM elements and allow the SDK to discover and wire them automatically. To activate declarative control detection set the `customControls` option to `true` in the map initialization configuration. Alternatively, customControls may be set to a **CSS selector string**, restricting autodetection to: - Elements matching the selector directly - Or elements whose **ancestor** matches the selector ### NPM module setup ```bash npm install --save @maptiler/sdk bootstrap ``` #### main.js ```js import { Map, MapStyle, config } from '@maptiler/sdk'; import '@maptiler/sdk/dist/maptiler-sdk.css'; import 'bootstrap/dist/css/bootstrap.min.css'; config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE'; const map = new Map({ container: 'map', // container's id or the HTML element to render the map style: MapStyle.STREETS, customControls: true, navigationControl: false, geolocateControl: false, terrainExaggeration: 4, }); //custom control (center map) document.querySelector(".home-button")?.addEventListener("click", () => map.easeTo({ center: [15, 50], zoom: 7 })); ``` #### index.html ```html Add a custom control declarative way | NPM example
``` #### style.css ```css body { margin: 0; padding: 0; } #map { position: absolute; top: 0; bottom: 0; width: 100%; } .maplibregl-control-container .btn { pointer-events: auto; display: block; } [data-maptiler-control="reset-view"] span { transform: rotateX(calc(var(--maptiler-pitch) * 1deg)) rotateZ(calc(var(--maptiler-bearing) * -1deg)); } [data-maptiler-control="toggle-projection"] span::after { content: "globe"; } @container style(--maptiler-is-globe-projection: true) { [data-maptiler-control="toggle-projection"] span::after { content: "map"; } } [data-maptiler-control="toggle-terrain"] span, .home-button span { transition: font-variation-settings 1s ease-in-out; font-variation-settings: 'FILL' 0; } @container style(--maptiler-has-terrain: true) { [data-maptiler-control="toggle-terrain"] span { font-variation-settings: 'FILL' 1; } } @container style(--maptiler-center-lng: 15) and style(--maptiler-center-lat: 50) { .home-button span { font-variation-settings: 'FILL' 1; } } ``` ### Basic JavaScript setup ```html MapTiler custom controls
``` ## Learn more Check out the [MaptilerExternalControl API reference](https://docs.maptiler.com/sdk-js/api/controls/#maptilerexternalcontrol) to learn all the options to add custom controls to your map interface. ## Related examples ### [Custom control programmatically](https://docs.maptiler.com/sdk-js/examples/custom-controls-programmatic/) Examples Programmatically add custom controls for dynamic map logic integration. ### [Add custom zoom control](https://docs.maptiler.com/sdk-js/examples/custom-control/) Examples Add custom zoom level control to your map interface. ### [Hide map navigation controls](https://docs.maptiler.com/sdk-js/examples/navigation/) Tutorials Hide the map navigation and zoom controls. ### [Scale control](https://docs.maptiler.com/sdk-js/examples/control-scale/) Tutorials Learn to add and display map scale control.