Layers

A layer, also known as a style layer, provides style instructions that describe the visual properties that apply when rendering the layer on a map. The required properties and available options are defined by the GL Style Specification.

Except for layers of the background type, each layer needs to refer to a source. Layers take the data that they get from a source, optionally filter features, and then define how those features are styled.

AnimatedRouteLayer

The AnimatedRouteLayer is a custom layer that animates a path or route on the map based on keyframes or GeoJSON data. It supports animated line styling and camera following, making it ideal for visualizing routes, playback tracks, or timeline-based geographic events.

Warning

Currently, there can only be one instance of AnimatedRouteLayer on the map at any time to avoid camera conflict issues from multiple concurrent animations. Remove any existing AnimatedRouteLayer instance from the map before adding another.

Features

Animate a path using keyframes or GeoJSON data
Optional animated stroke styles to indicate progress
Camera movement smoothing, following along the route
Configurable duration, easing, delay, and iterations via geojson properties
Event-based lifecycle hooks for adaptability
Optional manual frame advancement (e.g., for scrubbing or syncing with map events, scroll, etc.)

Source types: GeoJSONSource

Example


const myGeoJSONSource = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-74.0060, 40.7128],
          [-73.9352, 40.7306],
          [-73.9851, 40.7580]
        ]
      },
      "properties": {
        "@duration": 5000, // animation params are prepended with '@'
        "@iterations": 3,
        "@delay": 1000,
        "@autoplay": true,
        "bearing": [
          40,
          30,
          10,
          10,
          20,
          40,
        ]
      }
    }
  ]
}

map.addSource("my-geojson-source", {
  type: "geojson",
  data: myGeoJSONSource,
});

const animatedRoute = new AnimatedRouteLayer({
  source: {
    // assumes that the source is already added to the map with the given layer ID
    id: "my-geojson-source", // the name of the source
    layerID: "route-layer", // the name of the layer
  },
  // OR
  keyframes: [], // an array of keyframes

  duration: 5000,
  pathStrokeAnimation: {
    // will only be applied to LineString GeoJSON types
    activeColor: [0, 128, 0, 1], // color of the line that has already been traversed
    inactiveColor: [128, 128, 128, 0.5],
  },
  cameraAnimation: {
    follow: true, // should the camera follow the route?
    pathSmoothing: {
      resolution: 20, // the resolution of the smoothness 
      epsilon: 10, // how much the path is simplified before smoothing
    },
  },
  autoplay: true,
});

// Add to map
map.addLayer(animatedRoute);

// Playback controls
animatedRoute.play();
animatedRoute.pause();

Animations and animated routes

Background

The background style layer covers the entire map. Use a background style layer to configure a color or pattern to show below all other map content. Check out all the background layer options and properties.

Example


map.addLayer({
  "id": "background",
  "type": "background",
  "layout": {
    "visibility": "visible"
  },
  "paint": {
    "background-color": {
      "stops": [
        [
          6,
          "hsl(60,20%,85%)"
        ],
        [
          20,
          "hsl(60,24%,90%)"
        ]
      ]
    }
  }
});

Circle

The circle style layer renders one or more filled circles on a map. You can use a circle layer to configure the visual appearance of point or point collection features in vector tiles. A circle layer renders circles whose radii are measured in screen units. Check out all the circle layer options and properties.

Source types: GeoJSONSource | Vector

Example


// First add the source with the "null-island" id to the map
map.addSource('null-island', {
  type: 'geojson',
  data: {
    "type": "FeatureCollection",
    "features": [{
      "type": "Feature",
      "properties": { "name": "Null Island" },
      "geometry": {
        "type": "Point",
        "coordinates": [ 0, 0 ]
      }
    }]
  }
});

// Then add the layer to the map. Display the "null-island" source data
map.addLayer({
  'id': 'point',
  'source': 'null-island',
  'type': 'circle',
  'paint': {
    'circle-radius': 10,
    'circle-color': '#007cbf'
  }
});

Fill

The fill style layer renders one or more filled (and optionally stroked) polygons on a map. You can use a fill layer to configure the visual appearance of polygon or multipolygon features. Check out all the fill layer options and properties.

Source types: GeoJSONSource | Vector

Example


// First add the source with the "square" id to the map
map.addSource('square', {
  type: 'geojson',
  data: {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "properties": {},
        "geometry": {
          "coordinates": [[[-2.2240348228768596, 45.20404531546535], [-2.2240348228768596, 38.55848603574671], [7.2012758848702845, 38.55848603574671], [7.2012758848702845, 45.20404531546535], [-2.2240348228768596, 45.20404531546535]]],
          "type": "Polygon"
        }
      }
    ]
  }
});

// Then add the layer to the map. Display the "square" source data
map.addLayer({
  "id": "square-region",
  "source": "square",
  "type": "fill",
  "paint": {
    "fill-color": "#00ffff"
  }
});

Fill-extrusion

The fill-extrusion style layer renders one or more filled (and optionally stroked) extruded (3D) polygons on a map. You can use a fill-extrusion layer to configure the extrusion and visual appearance of polygon or multipolygon features. Check out all the fill-extrusion layer options and properties.

Source types: GeoJSONSource | Vector

Example


// First add the source with the "floorplan" id to the map
map.addSource('floorplan', {
  // GeoJSON Data source used in vector tiles, documented at
  // https://gist.github.com/ryanbaumann/a7d970386ce59d11c16278b90dde094d
  'type': 'geojson',
  'data': 'https://docs.maptiler.com/sdk-js/assets/indoor-3d-map.geojson'
});

// Then add the layer to the map. Display the "floorplan" source data
map.addLayer({
  'id': 'room-extrusion',
  'type': 'fill-extrusion',
  'source': 'floorplan',
  'paint': {
    // See the GL Style Specification for details on data expressions.
    // https://docs.maptiler.com/gl-style-specification/expressions/
    
    // Get the fill-extrusion-color from the source 'color' property.
    'fill-extrusion-color': ['get', 'color'],
    
    // Get fill-extrusion-height from the source 'height' property.
    'fill-extrusion-height': ['get', 'height'],
    
    // Get fill-extrusion-base from the source 'base_height' property.
    'fill-extrusion-base': ['get', 'base_height'],
    
    // Make extrusions slightly opaque for see through indoor walls.
    'fill-extrusion-opacity': 0.5
  }
});

Heatmap

The heatmap style layer renders a range of colors to represent the density of points in an area. Check out all the heatmap layer options and properties.

Source types: GeoJSONSource | Vector

Example


// First add the source with the "earthquakes" id to the map
// Add a geojson point source. Heatmap layers also work with a vector tile source.
map.addSource('earthquakes', {
  'type': 'geojson',
  'data': 'https://docs.maptiler.com/sdk-js/assets/earthquakes.geojson'
});

// Then add the layer to the map. Display the "earthquakes" source data
map.addLayer(
  {
    'id': 'earthquakes-heat',
    'type': 'heatmap',
    'source': 'earthquakes',
    'maxzoom': 9,
    'paint': {
      // Increase the heatmap weight based on frequency and property magnitude
      'heatmap-weight': [
        'interpolate',
        ['linear'],
        ['get', 'mag'],
        0,
        0,
        6,
        1
      ],
      // Increase the heatmap color weight by zoom level
      // heatmap-intensity is a multiplier on top of heatmap-weight
      'heatmap-intensity': [
        'interpolate',
        ['linear'],
        ['zoom'],
        0,
        1,
        9,
        3
      ],
      // Color ramp for heatmap. Domain is 0 (low) to 1 (high).
      // Begin color ramp at 0-stop with a 0-transparency color to create a blur-like effect.
      'heatmap-color': [
        'interpolate',
        ['linear'],
        ['heatmap-density'],
        0,
        'rgba(33,102,172,0)',
        0.2,
        'rgb(103,169,207)',
        0.4,
        'rgb(209,229,240)',
        0.6,
        'rgb(253,219,199)',
        0.8,
        'rgb(239,138,98)',
        1,
        'rgb(178,24,43)'
      ],
      // Adjust the heatmap radius by zoom level
      'heatmap-radius': [
        'interpolate',
        ['linear'],
        ['zoom'],
        0,
        2,
        9,
        20
      ],
      // Transition from heatmap to circle layer by zoom level
      'heatmap-opacity': [
        'interpolate',
        ['linear'],
        ['zoom'],
        7,
        1,
        9,
        0
      ]
    }
  }
);

Create a heatmap layer

Hillshade

The hillshade style layer renders digital elevation model (DEM) data on the client side. The implementation only supports Terrain RGB and Mapzen Terrarium tiles. Check out all the hillshade layer options and properties.

Source types: Raster DEM

Example


const key = "YOUR_MAPTILER_API_KEY_HERE";
// First add the source with the "hillshadeSource" id to the map
map.addSource("hillshadeSource", {
  "type": "raster-dem",
  "url": `https://api.maptiler.com/tiles/terrain-rgb-v2/tiles.json?key=${key}`
});

// Then add the layer to the map. Display the "hillshadeSource" source data
map.addLayer({
  id: 'hills',
  type: 'hillshade',
  source: 'hillshadeSource',
  layout: { visibility: 'visible' },
  paint: { 'hillshade-shadow-color': '#473B24' }
});

Line

The line style layer renders one or more stroked polylines on the map. You can use a line layer to configure the visual appearance of polyline or multipolyline features. Check out all the line layer options and properties.

Source types: GeoJSONSource | Vector

Example


// First add the source with the "route" id to the map
map.addSource('route', {
  'type': 'geojson',
  'data': {
    'type': 'Feature',
    'properties': {},
    'geometry': {
      'type': 'LineString',
      'coordinates': [ [-122.48369693756104, 37.83381888486939], [-122.48348236083984, 37.83317489144141], [-122.48339653015138, 37.83270036637107], [-122.48356819152832, 37.832056363179625], [-122.48404026031496, 37.83114119107971], [-122.48404026031496, 37.83049717427869], [-122.48348236083984, 37.829920943955045], [-122.48356819152832, 37.82954808664175], [-122.48507022857666, 37.82944639795659], [-122.48610019683838, 37.82880236636284], [-122.48695850372314, 37.82931081282506], [-122.48700141906738, 37.83080223556934], [-122.48751640319824, 37.83168351665737], [-122.48803138732912, 37.832158048267786], [-122.48888969421387, 37.83297152392784], [-122.48987674713133, 37.83263257682617], [-122.49043464660643, 37.832937629287755], [-122.49125003814696, 37.832429207817725], [-122.49163627624512, 37.832564787218985], [-122.49223709106445, 37.83337825839438], [-122.49378204345702, 37.83368330777276] ]
    }
  }
});

// Then add the layer to the map. Display the "route" source data
map.addLayer({
  'id': 'route',
  'type': 'line',
  'source': 'route',
  'layout': {
    'line-join': 'round',
    'line-cap': 'round'
  },
  'paint': {
    'line-color': '#888',
    'line-width': 8
  }
});

Raster

The raster style layer renders raster tile data on a map, such as satellite imagery or aerial overlays. Check out all the raster layer options and properties.

Source types: ImageSource | Raster | VideoSource

Example


// First add the source with the "aerial-source" id to the map
map.addSource("aerial-source", {
  "type": "image",
  "url": "https://docs.maptiler.com/sdk-js/examples/raster-layer/img/aerial_wgs84.png",
  "coordinates": [
    [4.639663696289062, 50.900867668253724],
    [4.642066955566406, 50.900867668253724],
    [4.642066955566406, 50.89935199434383],
    [4.639663696289062, 50.89935199434383]
  ]
});

// Then add the layer to the map. Display the "aerial-source" source data
map.addLayer({
  "id": "overlay",
  "source": "aerial-source",
  "type": "raster",
  "paint": {
    "raster-opacity": 0.85
  }
});

Symbol

The symbol style layer renders icon and text labels at points or along lines on a map. You can use a symbol layer to configure the visual appearance of labels for features in vector tiles. Check out all the symbol layer options and properties.

Source types: GeoJSONSource | Vector

Example


// First add the source with the "airports" id to the map
map.addSource('airports', {
  type: 'geojson',
  data: 'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_10m_ports.geojson'
});

// Load the icon image or use an image defined in the sprite
const image = await map.loadImage('https://docs.maptiler.com/sdk-js/examples/geojson-point/icon-plane-512.png');
map.addImage('plane', image.data);

// Then add the layer to the map. Display the "airports" source data
map.addLayer({
  'id': 'airports',
  'type': 'symbol',
  'source': 'airports',
  'layout': {
    'icon-image': 'plane',
    'icon-size': ['*', ['get', 'scalerank'] ,0.01]
  },
  'paint': {}
});

Layers

AnimatedRouteLayer

Features

Example

Related examples

Background

Example

Circle

Example

Related examples

Fill

Example

Related examples

Fill-extrusion

Example

Related examples

Heatmap

Example

Related examples

Hillshade

Example

Related examples

Line

Example

Related examples

Raster

Example

Related examples

Symbol

Example

Related examples