---
title: "How to display a map legend control to toggle layers visualization | JavaScript maps SDK"
description: "Display a map legend control to toggle layer visibility."
---

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

# How to display a map legend control to toggle layers visualization

This tutorial demonstrates the process of presenting a map legend control that allows for the toggling of layer visualization.

By following this guide, users will learn how to display a control panel that showcases the various layers of a map and enables them to easily turn on or off specific layers as needed. This functionality provides a convenient way for users to customize their map viewing experience, allowing them to focus on specific layers of interest while hiding others.

## NPM module setup

1.  Install the npm package.
    
    ```bash
    npm install --save @maptiler/sdk
    ```
    
2.  Include the CSS file.
    
    If you have a bundler that can handle CSS, you can `import` the CSS
    
    ```js
    import "@maptiler/sdk/dist/maptiler-sdk.css";
    ```
    
    or include it with a `<link />` in the head of the document via the CDN
    
    ```html
    <link href='https://cdn.maptiler.com/maptiler-sdk-js/v4.2.0/maptiler-sdk.css' rel='stylesheet' />
    ```
    
3.  Include the following code in your JavaScript file (Example: app.js).
    
    ```js
    import * as maptilersdk from '@maptiler/sdk';
    
     maptilersdk.config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';
     const map = new maptilersdk.Map({
       container: 'map', // container's id or the HTML element to render the map
       style: maptilersdk.MapStyle.STREETS,
          
       center: [139.75626, 35.68254], // starting position [lng, lat]
       zoom: 13.85, // starting zoom
          
     });
    ```
    
4.  Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [secure the key](https://docs.maptiler.com/guides/credentials/api-key/#secure-key) before you publish it.
    
5.  The next is up to you. You can center your map wherever you desire (modifying the `starting position`) and set an appropriate zoom level (modifying the `starting zoom`) to match your users’ needs. Additionally, you can change the map’s look (by updating the `source URL`); choose from a range of visually appealing map styles from our extensive [MapTiler standard maps](https://cloud.maptiler.com/maps/), or create your own to truly differentiate your application.
    
6.  Include the `maplibre-gl-legend` JavaScript and CSS files in the `head` of your HTML file. To create the legend we will use the [maplibre-gl-legend](https://github.com/watergis/maplibre-gl-legend) plugin.
    
    ```html
    <link href='https://www.unpkg.com/@watergis/maplibre-gl-legend@latest/dist/maplibre-gl-legend.css' rel='stylesheet' />
     <script src="https://www.unpkg.com/@watergis/maplibre-gl-legend@latest/dist/maplibre-gl-legend.umd.js"></script>
    ```
    
7.  Add event handler for map `load` event. You will add code to create a vector source and a vector layer in this handler.
    
    ```js
    map.on('load', function() {
        
     });
    ```
    
8.  Create the list of layers that we want to show in the legend. For each layer we must create a key:value pair where the key is the ID of the layer in the map style and the value is text that is displayed in the legend.
    
    ```js
    map.on('load', function() {
       const targets = {
         Residential: "Residential",
         Water: "Water",
         Building: "Building",
         Airport: "Airport",
         "Other POI": "Pois",
       };
     });
    ```
    
9.  Add the `maplibre-gl-legend` control to the map.
    
    ```js
    map.on('load', function() {
       const targets = {
         Residential: "Residential",
         Water: "Water",
         Building: "Building",
         Airport: "Airport",
         "Other POI": "Pois",
       };
       const options = {
         showDefault: true,
         showCheckbox: true,
         onlyRendered: true,
         reverseOrder: true
       };
       map.addControl(new MaplibreLegendControl.MaplibreLegendControl(targets, options), "bottom-left");
     });
    ```
    

## Basic JavaScript setup

1.  Copy the following code, paste it into your favorite text editor, and save it as a `.html` file.
    
    ```html
    <!DOCTYPE html>
     <html lang="en">
     <head>
       <meta charset="UTF-8">
       <meta name="viewport" content="width=device-width, initial-scale=1.0">
       <title>Display a map legend control to toggle layers visualization</title>
       <script src="https://cdn.maptiler.com/maptiler-sdk-js/v4.2.0/maptiler-sdk.umd.min.js"></script>
       <link href="https://cdn.maptiler.com/maptiler-sdk-js/v4.2.0/maptiler-sdk.css" rel="stylesheet" />
       <style>
         body { margin: 0; padding: 0; }
         #map { position: absolute; top: 0; bottom: 0; width: 100%; }
       </style>
     </head>
     <body>
       <div id="map"></div>
       <script>
           maptilersdk.config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';      
           const map = new maptilersdk.Map({
             container: 'map', // container's id or the HTML element to render the map
             style: maptilersdk.MapStyle.STREETS,
                
             center: [139.75626, 35.68254], // starting position [lng, lat]
             zoom: 13.85, // starting zoom
                
           });
       </script>
     </body>
     </html>
    ```
    
2.  Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [secure the key](https://docs.maptiler.com/guides/credentials/api-key/#secure-key) before you publish it.
    
3.  The next is up to you. You can center your map wherever you desire (modifying the `starting position`) and set an appropriate zoom level (modifying the `starting zoom`) to match your users’ needs. Additionally, you can change the map’s look (by updating the `source URL`); choose from a range of visually appealing map styles from our extensive [MapTiler standard maps](https://cloud.maptiler.com/maps/), or create your own to truly differentiate your application.
    
4.  Include the `maplibre-gl-legend` JavaScript and CSS files in the `head` of your HTML file. To create the legend we will use the [maplibre-gl-legend](https://github.com/watergis/maplibre-gl-legend) plugin.
    
    ```html
    <link href='https://www.unpkg.com/@watergis/maplibre-gl-legend@latest/dist/maplibre-gl-legend.css' rel='stylesheet' />
     <script src="https://www.unpkg.com/@watergis/maplibre-gl-legend@latest/dist/maplibre-gl-legend.umd.js"></script>
    ```
    
5.  Add event handler for map `load` event. You will add code to create a vector source and a vector layer in this handler.
    
    ```js
    map.on('load', function() {
        
     });
    ```
    
6.  Create the list of layers that we want to show in the legend. For each layer we must create a key:value pair where the key is the ID of the layer in the map style and the value is text that is displayed in the legend.
    
    ```js
    map.on('load', function() {
       const targets = {
         Residential: "Residential",
         Water: "Water",
         Building: "Building",
         Airport: "Airport",
         "Other POI": "Pois",
       };
     });
    ```
    
7.  Add the `maplibre-gl-legend` control to the map.
    
    ```js
    map.on('load', function() {
       const targets = {
         Residential: "Residential",
         Water: "Water",
         Building: "Building",
         Airport: "Airport",
         "Other POI": "Pois",
       };
       const options = {
         showDefault: true,
         showCheckbox: true,
         onlyRendered: true,
         reverseOrder: true
       };
       map.addControl(new MaplibreLegendControl.MaplibreLegendControl(targets, options), "bottom-left");
     });
    ```
    

### Complete source code

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Display a map legend control to toggle layers visualization</title>
  <script src="https://cdn.maptiler.com/maptiler-sdk-js/v4.2.0/maptiler-sdk.umd.min.js"></script>
  <link href="https://cdn.maptiler.com/maptiler-sdk-js/v4.2.0/maptiler-sdk.css" rel="stylesheet" />
  <link href='https://www.unpkg.com/@watergis/maplibre-gl-legend@latest/dist/maplibre-gl-legend.css' rel='stylesheet' />
  <script src="https://www.unpkg.com/@watergis/maplibre-gl-legend@latest/dist/maplibre-gl-legend.umd.js"></script>
  <style>
    body {
      margin: 0;
      padding: 0;
    }
    #map {
      position: absolute;
      top: 0;
      bottom: 0;
      width: 100%;
    }
  </style>
</head>
<body>
  <div id="map"></div>
  <script>
      maptilersdk.config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';
      const map = new maptilersdk.Map({
        container: 'map', // container id
        style: maptilersdk.MapStyle.STREETS, 
        center: [16.62662018, 49.2125578], // starting position [lng, lat]
        zoom: 10, // starting zoom
      });
      map.on('load', () => {
        const targets = {
          Residential: "Residential",
          Water: "Water",
          Building: "Building",
          Airport: "Airport",
          "Other POI": "Pois",
        };
        const options = {
          showDefault: true,
          showCheckbox: true,
          onlyRendered: false,
          reverseOrder: true
        };
        map.addControl(new MaplibreLegendControl.MaplibreLegendControl(targets, options), "bottom-left");
      });
      
  </script>
</body>
</html>
```

## Learn more

Check out the [MapTiler Planet schema](https://docs.maptiler.com/schema/planet/) to know how it is organized into different thematic layers and which attribute and values each layer contains.

Visit the [JavaScript Maps API reference](https://docs.maptiler.com/sdk-js/api/controls/) to learn how to create your custom control.

## Related examples

### [Minimap control](https://docs.maptiler.com/sdk-js/examples/control-minimap/)

Tutorials

Display an overview minimap control to aid map navigation.

### [Add elevation profile control](https://docs.maptiler.com/sdk-js/examples/elevation-profile-control-simple/)

Examples

Show elevation profiles for GeoJSON traces using MapTiler.

### [Choropleth legend](https://docs.maptiler.com/sdk-js/examples/control-legend-choropleth/)

Tutorials

Implement an interactive legend control for a choropleth map.

### [Change attribution default position](https://docs.maptiler.com/sdk-js/examples/attribution-position/)

Examples

Position map attribution in the top-left corner on initialization.