---
title: "Create custom marker overlays using the Marker Layout | Marker layout | JavaScript maps SDK"
description: "Create custom non-colliding marker overlays on your map using the Marker Layout on top of MapTiler SDK. ."
---

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

# Create custom marker overlays using the Marker Layout

Create custom non-colliding marker overlays on your map using the [Marker Layout](https://docs.maptiler.com/sdk-js/modules/marker-layout/) on top of MapTiler SDK.

This example shows how to display the information from the city and town label layers. In this case, we are not applying any filters because we want to create as many markers as possible. To improve performance, we will _soft update_ the markers when the user moves the map and complete the update once the user stops moving the map.

### NPM module setup

```bash
npm install --save @maptiler/sdk @maptiler/marker-layout
```

#### main.js

```js
import { Map, MapStyle, config } from '@maptiler/sdk';
import '@maptiler/sdk/dist/maptiler-sdk.css';
import { MarkerLayout } from '@maptiler/marker-layout';

const appContainer = document.getElementById('map');

  config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';
  
   // Creating a map
   const map = new Map({
    container: appContainer,
    style: MapStyle.STREETS,
    zoom: 9.14,
    center: [13.3608, 52.5478],
  });

  // Creating the div that will contain all the markers
  const markerContainer = document.createElement("div");
  appContainer.appendChild(markerContainer);

  (async () => {
    await map.onReadyAsync();

    const markerManager = new MarkerLayout(map, {
      layers: ["Capital city labels", "City labels", "Place labels", "Town labels"],
      markerSize: [140, 80],
      markerAnchor: "top",
      offset: [0, -8], // so that the tip of the marker bottom pin lands on the city dot
      sortingProperty: "rank",

      // no filtering so that we get as many features as possible
    });

    // This object contains the marker DIV so that they can be updated rather than fully recreated every time
    const markerLogicContainer = {};

    let markerStatus = null;

    // This function will be used as the callback for some map events
    const updateMarkers = () => {
      markerStatus = markerManager.update();

      if (!markerStatus) return;

      // Remove the div that corresponds to removed markers
      markerStatus.removed.forEach((abstractMarker) => {
        const markerDiv = markerLogicContainer[abstractMarker.id];
        delete markerLogicContainer[abstractMarker.id];
        markerContainer.removeChild(markerDiv);
      });

      // Update the div that corresponds to updated markers
      markerStatus.updated.forEach((abstractMarker) => {
        const markerDiv = markerLogicContainer[abstractMarker.id];
        updateMarkerDiv(abstractMarker, markerDiv);
      });

      // Create the div that corresponds to the new markers
      markerStatus.new.forEach((abstractMarker) => {
        const markerDiv = makeMarker(abstractMarker);
        markerLogicContainer[abstractMarker.id] = markerDiv;
        markerContainer.appendChild(markerDiv);
      });
    }

    const softUpdateMarkers = () => {
      // A previous run of .update() yieding no result or not being ran at all
      // would stop the soft update
      if (!markerStatus) return;

      markerStatus.updated.forEach((abstractMarker) => {
        markerManager.softUpdateAbstractMarker(abstractMarker);
        const markerDiv = markerLogicContainer[abstractMarker.id];
        updateMarkerDiv(abstractMarker, markerDiv);
      })

      markerStatus.new.forEach((abstractMarker) => {
        markerManager.softUpdateAbstractMarker(abstractMarker);
        const markerDiv = markerLogicContainer[abstractMarker.id];
        updateMarkerDiv(abstractMarker, markerDiv);
      })
    }

    // While moving the map, this event is triggered many times per seconds
    // so we only perform a soft update (that could be debounced)
    map.on("move", softUpdateMarkers);

    // When done moving, we perform a full update
    map.on("moveend", updateMarkers)

    // Full update at init
    updateMarkers();
  })()

function makeMarker(abstractMarker) {

  const marker = document.createElement("div");
  marker.classList.add("marker");
  marker.classList.add('fade-in-animation');
  marker.style.setProperty("width", `${abstractMarker.size[0]}px`);
  marker.style.setProperty("height", `${abstractMarker.size[1]}px`);
  marker.style.setProperty("transform", `translate(${abstractMarker.position[0]}px, ${abstractMarker.position[1]}px)`);

  const feature = abstractMarker.features[0];

  marker.innerHTML = `
    <div class="markerPointy"></div>
    <div class="markerBody">
      
      <div class="markerTop">
        ${feature.properties["name:en"] || feature.properties["name"]}
      </div>
      
      <div class="markerBottom">
        <ul>
          <li><b>Name:</b> ${feature.properties.name}</li>
          <li><b>Class:</b> ${feature.properties.class}</li>
          <li><b>Rank:</b> ${feature.properties.rank}</li>
        </ul>
      </div>
    </div>
  `
  return marker;
}

function updateMarkerDiv(abstractMarker, marker) {
  marker.style.setProperty("width", `${abstractMarker.size[0]}px`);
  marker.style.setProperty("height", `${abstractMarker.size[1]}px`);
  marker.style.setProperty("transform", `translate(${abstractMarker.position[0]}px, ${abstractMarker.position[1]}px)`);
}
```

#### index.html

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="robots" content="noindex">
  <title>Create custom marker overlays using the Marker Layout | NPM example</title>
  <link rel="stylesheet" href="./style.css">
</head>
<body>
  <div id="map"></div>
  <script type="module" src="./main.js"></script>
</body>
</html>
```

#### style.css

```css
body {
  margin: 0;
  padding: 0;
  font-family: sans-serif;
}

ul {
  list-style-type: none;
  padding: 0;
  margin: 5px;
}

#map {
  position: absolute;
  top: 0;
  bottom: 0;
  width: 100%;
}

.marker {
  position: absolute;
  pointer-events: none;
  color: #000;
  line-height: 12px;
  box-shadow: #00000040 0px 2px 10px;
}

.markerPointy {
  width: 12px;
  height: 12px;
  background-color: #e6e6e6;
  position: absolute;
  transform: rotate(45deg) translate(-70%);
  bottom: -12px;
  left: 0;
  right: -12px;
  margin: auto;
  box-shadow: #00000040 0px 2px 10px;
}

.markerBody {
  position: absolute;
  background: #e6e6e6;
  width: 100%;
  height: 100%;
  top: 0;
  border-radius: 2px;
  /* padding: 3px;  */
}

.markerTop {
  border-top-left-radius: inherit;
  border-top-right-radius: inherit;
  width: 100%;
  height: 20px;
  line-height: 20px;
  text-align: center;
  background: #593895;
  color: white;
  font-size: 15px;
  font-weight: 400;
}

.markerBottom {
  border-radius: inherit;
  width: 100%;
  height: calc(100% - 20px);
  display: flex;
}

@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

.fade-in-animation {
  animation: fadeIn 0.5s ease forwards;
}
```

### Basic JavaScript setup

```html
<html>
  <head>
    <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
    <title>MapTiler Marker Layout</title>
    <!-- Importing MapTiler SDK -->
    <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" />

    <!-- Importing MapTiler Marker Layout -->
    <script src="https://cdn.maptiler.com/maptiler-marker-layout/v2.0.1/maptiler-marker-layout.umd.min.js"></script>

    <style>
      body {
      margin: 0;
      padding: 0;
      font-family: sans-serif;
    }

    ul {
      list-style-type: none;
      padding: 0;
      margin: 5px;
    }

    #map {
      position: absolute;
      top: 0;
      bottom: 0;
      width: 100%;
    }

    .marker {
      position: absolute;
      pointer-events: none;
      color: #000;
      line-height: 12px;
      box-shadow: #00000040 0px 2px 10px;
    }

    .markerPointy {
      width: 12px;
      height: 12px;
      background-color: #e6e6e6;
      position: absolute;
      transform: rotate(45deg) translate(-70%);
      bottom: -12px;
      left: 0;
      right: -12px;
      margin: auto;
      box-shadow: #00000040 0px 2px 10px;
    }

    .markerBody {
      position: absolute;
      background: #e6e6e6;
      width: 100%;
      height: 100%;
      top: 0;
      border-radius: 2px;
      /* padding: 3px;  */
    }

    .markerTop {
      border-top-left-radius: inherit;
      border-top-right-radius: inherit;
      width: 100%;
      height: 20px;
      line-height: 20px;
      text-align: center;
      background: #593895;
      color: white;
      font-size: 15px;
      font-weight: 400;
    }

    .markerBottom {
      border-radius: inherit;
      width: 100%;
      height: calc(100% - 20px);
      display: flex;
    }

    @keyframes fadeIn {
      from { opacity: 0; }
      to { opacity: 1; }
    }

    .fade-in-animation {
      animation: fadeIn 0.5s ease forwards;
    }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script>

      const appContainer = document.getElementById('map');

      maptilersdk.config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';
      
       // Creating a map
       const map = new maptilersdk.Map({
        container: appContainer,
        style: maptilersdk.MapStyle.STREETS,
        zoom: 9.14,
        center: [13.3608, 52.5478],
      });

      // Creating the div that will contain all the markers
      const markerContainer = document.createElement("div");
      appContainer.appendChild(markerContainer);

      (async () => {
        await map.onReadyAsync();

        const markerManager = new maptilermarkerlayout.MarkerLayout(map, {
          layers: ["Capital city labels", "City labels", "Place labels", "Town labels"],
          markerSize: [140, 80],
          markerAnchor: "top",
          offset: [0, -8], // so that the tip of the marker bottom pin lands on the city dot
          sortingProperty: "rank",

          // no filtering so that we get as many features as possible
        });

        // This object contains the marker DIV so that they can be updated rather than fully recreated every time
        const markerLogicContainer = {};

        let markerStatus = null;

        // This function will be used as the callback for some map events
        const updateMarkers = () => {
          markerStatus = markerManager.update();

          if (!markerStatus) return;

          // Remove the div that corresponds to removed markers
          markerStatus.removed.forEach((abstractMarker) => {
            const markerDiv = markerLogicContainer[abstractMarker.id];
            delete markerLogicContainer[abstractMarker.id];
            markerContainer.removeChild(markerDiv);
          });

          // Update the div that corresponds to updated markers
          markerStatus.updated.forEach((abstractMarker) => {
            const markerDiv = markerLogicContainer[abstractMarker.id];
            updateMarkerDiv(abstractMarker, markerDiv);
          });

          // Create the div that corresponds to the new markers
          markerStatus.new.forEach((abstractMarker) => {
            const markerDiv = makeMarker(abstractMarker);
            markerLogicContainer[abstractMarker.id] = markerDiv;
            markerContainer.appendChild(markerDiv);
          });
        }

        const softUpdateMarkers = () => {
          // A previous run of .update() yieding no result or not being ran at all
          // would stop the soft update
          if (!markerStatus) return;

          markerStatus.updated.forEach((abstractMarker) => {
            markerManager.softUpdateAbstractMarker(abstractMarker);
            const markerDiv = markerLogicContainer[abstractMarker.id];
            updateMarkerDiv(abstractMarker, markerDiv);
          })

          markerStatus.new.forEach((abstractMarker) => {
            markerManager.softUpdateAbstractMarker(abstractMarker);
            const markerDiv = markerLogicContainer[abstractMarker.id];
            updateMarkerDiv(abstractMarker, markerDiv);
          })
        }

        // While moving the map, this event is triggered many times per seconds
        // so we only perform a soft update (that could be debounced)
        map.on("move", softUpdateMarkers);

        // When done moving, we perform a full update
        map.on("moveend", updateMarkers)

        // Full update at init
        updateMarkers();
      })()

    function makeMarker(abstractMarker) {

      const marker = document.createElement("div");
      marker.classList.add("marker");
      marker.classList.add('fade-in-animation');
      marker.style.setProperty("width", `${abstractMarker.size[0]}px`);
      marker.style.setProperty("height", `${abstractMarker.size[1]}px`);
      marker.style.setProperty("transform", `translate(${abstractMarker.position[0]}px, ${abstractMarker.position[1]}px)`);

      const feature = abstractMarker.features[0];

      marker.innerHTML = `
        <div class="markerPointy"></div>
        <div class="markerBody">
          
          <div class="markerTop">
            ${feature.properties["name:en"] || feature.properties["name"]}
          </div>
          
          <div class="markerBottom">
            <ul>
              <li><b>Name:</b> ${feature.properties.name}</li>
              <li><b>Class:</b> ${feature.properties.class}</li>
              <li><b>Rank:</b> ${feature.properties.rank}</li>
            </ul>
          </div>
        </div>
      `
      return marker;
    }

    function updateMarkerDiv(abstractMarker, marker) {
      marker.style.setProperty("width", `${abstractMarker.size[0]}px`);
      marker.style.setProperty("height", `${abstractMarker.size[1]}px`);
      marker.style.setProperty("transform", `translate(${abstractMarker.position[0]}px, ${abstractMarker.position[1]}px)`);
    }
    </script>
  </body>
</html>
```

## Learn more

Check out the [Marker Layout JS module reference](https://docs.maptiler.com/sdk-js/modules/marker-layout/)

## Related examples

### [Weather custom popup](https://docs.maptiler.com/sdk-js/examples/weather-custom-popup/)

Examples

Create highly customizable popups for weather maps using MarkerLayout.

### [Filtered Marker Layout](https://docs.maptiler.com/sdk-js/examples/marker-layout-basic/)

Examples

Create non-colliding marker overlays to display the information from the city and town label layers.

### [Weather icons Marker Layout](https://docs.maptiler.com/sdk-js/examples/marker-layout-weather/)

Examples

Create a weather map using the Marker Layout to show your custom weather markers icons, animated SVGs or Lotties.

### [Add interaction to landmarks](https://docs.maptiler.com/sdk-js/examples/landmarks-interactions/)

Examples

Create a map with custom landmarks and add interactions like popups to display additional information.