---
title: "Helpers | JavaScript maps SDK"
description: "Helper functions to simplify creating sources and layers."
---

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

# Helpers ![MapTiler logo](https://docs.maptiler.com/favicon.ico)

Helpers are a set of functions to facilitate the creation of sources and layers. All the helpers are made available under the `helpers` object.

**Example**

```js
maptilersdk.helpers.addPolyline(map, {
  // Dataset UUID or URL (relative or absolute)
  data: "some-trace.geojson",
});
```

```js
import { helpers } from "@maptiler/sdk";

helpers.addPolyline(map, {
  // Dataset UUID or URL (relative or absolute)
  data: "some-trace.geojson",
});
```

## Vector layer helpers

Adding vector layers usually requires creating a source first and then configuring many paint and layout style options. Helper functions simplify this process by combining source and layer creation into a single step.

![](./img/point-layer.webp)

Vector layer helpers:

-   [Polyline layer helper](#polyline)
-   [Polygon layer helper](#polygon)
-   [Point layer helper](#point)
-   [Heatmap layer helper](#heatmap)

## Shared logic

Helpers come with a lot of **built-in defaults** and some fail-proof logic that makes creating vector layers much easier! As a result, a dataset can be displayed in one call, creating both the datasource and the layer(s) in one go!

Depending on the type of feature to add ([point](#point), [polyline](#polyline), [polygon](#polygon) or [heatmap](#heatmap)), a different helper function needs to be used, but datasource could contain mixed types of feature and the helper will only display a specific type. **Example:** we have a _geoJSON_ file that contains both _polygons_ and _point_ and we use it as the data property on the `helpers.addPoint(map, {options})`, this will only add the _points_.

In addition to easy styling, helper’s datasource can be:

-   a URL to a geoJSON file or its string content
-   a URL to a GPX or KML file (only for the polyline helper) or its string content
-   a UUID of a [MapTiler dataset](https://cloud.maptiler.com/data/)

### Multiple layers

The key design principle of these vector layers helpers is **it’s easy to make what you want**. Helpers can create multiple layers to represent the symbolization of a layer, if necessary.

#### Example

To create a road with an outline with the [polyline layer helper](#polyline), you just say if you want an outline and specify its size (or even a zoom dependant size) and everything is handled for you. As a result, the `helpers.addPolyline` method will return an object with **multiple IDs**: ID of the top/main layer, ID of the outline layer (could be `null`) and the ID of the data source. This makes further layer and source manipulation possible.

Without the helpers to create a road with an outline, one must draw two layers: a wider base layer and a narrower top layer, fueled by the same polyline data. This requires ordering the layers properly and computing not the width of the outline, but rather the width of the polyline underneath so that it outgrows the top road layer of the desired number of pixels.

### CommonShapeLayerOptions

The vector layer helper also share some _I/O_ logic: each of them can take many options but a subset of them is common across all the helpers:

[Type Alias CommonShapeLayerOptions](https://docs.maptiler.com/sdk-js/api-reference/types/CommonShapeLayerOptions/)

## Polyline layer helper

The polyline helper makes it easy to create vector layers that contain polylines. Whenever it’s possible and it makes sense, we use the same terminology across the different helpers.

![](./img/default-trace.webp)

### API reference

The method `helpers.addPolyline` is not only compatible with the traditionnal **GeoJSON** source but also with **GPX** and **KML** files and the `data` option can be a MapTiler dataset UUID and will be resolved automatically.

Minimal usage, with the default line width and a random color (withing a selected list):

```js
import { helpers } from "@maptiler/sdk";

helpers.addPolyline(map, { 
  // dataset UUID, a URL (relative or absolute) 
  data: "some-trace.geojson",
});
```

[Function addPolyline](https://docs.maptiler.com/sdk-js/api-reference/functions/addPolyline/)

### Examples

Check out the full list of [examples](https://docs.maptiler.com/sdk-js/examples/?q=polyline+helper).

We can add many options, such a a specific color, a custom width or a dash pattern, this time sourcing the data from MapTiler, using the UUID of a dataset:

```js
import { helpers } from "@maptiler/sdk";

helpers.addPolyline(map, { 
  data: "74003ba7-215a-4b7e-8e26-5bbe3aa70b05",
  lineColor: "#FF6666",
  lineWidth: 4,
  lineDashArray: "____ _ ",
  lineCap: "butt",
});
```

![](./img/custom-trace.webp)

As you can see, we’ve come up with a fun and easy way to create **dash arrays**, just use underscores and white spaces and this pattern will repeat!

Adding an outline is also pretty straightforward:

```js
import { helpers } from "@maptiler/sdk";

helpers.addPolyline(map, { 
  data: "74003ba7-215a-4b7e-8e26-5bbe3aa70b05",
  lineColor: "#880000",
  outline: true,
});
```

![](./img/polyline-outline.webp)

Endless possibilities, what about a glowing wire?

```js
import { helpers } from "@maptiler/sdk";

helpers.addPolyline(map, { 
  data: "74003ba7-215a-4b7e-8e26-5bbe3aa70b05",
  lineColor: "#fff",
  lineWidth: 1,
  outline: true,
  outlineColor: "#ca57ff",
  outlineWidth: 2,
  outlineWidth: 10,
  outlineBlur: 10,
  outlineOpacity: 0.5,
});
```

![](./img/polyline-glow.webp)

View more [Polyline layer helper examples](https://docs.maptiler.com/sdk-js/examples/?q=polyline+helper).

## Polygon layer helper

The polygon helper makes it easy to create vector layers that contain polygons, whether they are _multipolygons_, _holedpolygons_ or just simple _polygons_. Whenever it’s possible and it makes sense, we use the same terminology across the different helpers.

![](./img/polygon-transparent.webp)

### API reference

Minimal usage, with a half-transparent and a random color (withing a selected list) polygon of Switzerland, from a local file:

```js
import { helpers } from "@maptiler/sdk";

helpers.addPolygon(map, {
  data: "switzerland.geojson",
  fillOpacity: 0.5,
});
```

[Function addPolygon](https://docs.maptiler.com/sdk-js/api-reference/functions/addPolygon/)

### Examples

Check out the full list of [examples](https://docs.maptiler.com/sdk-js/examples/?q=polygon+helper).

We can add many options, such a a specific color, a custom width or a pattern, this time sourcing the data from MapTiler, using the UUID of a dataset:

```js
import { helpers } from "@maptiler/sdk";

helpers.addPolygon(map, { 
  data: "aa203ccf-25ee-4447-bef3-55f90916897a",
  pattern: "cheese512.webp",
  outline: true,
  outlineWidth: 3,
  outlineColor: "white",
  outlineDashArray: "_ ",
  fillOpacity: 0.7,
});
```

![](./img/swiss-cheese.webp)

View more [Polygon layer helper examples](https://docs.maptiler.com/sdk-js/examples/?q=polygon+helper).

## Point layer helper

A point visualisation may appear like the simplest of all, but we noticed this is where people get the most creative: cluster, data-drive variable radius, but also scaled with zoom, with or without labels, data-driven colors, etc. Our helper supports all of these and will fill-in with built-in default for what’s missing. Whenever it’s possible and it makes sense, we use the same terminology across the different helpers.

![](./img/points.webp)

### API reference

Here is the simplest example, with a dataset loaded from a local file (if no color is specified, a random color is used and the default radius is ramped over the zoom level):

```js
import { helpers } from "@maptiler/sdk";

helpers.addPoint(map, {
  data: "public-schools.geojson",
});
```

[Function addPoint](https://docs.maptiler.com/sdk-js/api-reference/functions/addPoint/)

### Examples

Check out the full list of [examples](https://docs.maptiler.com/sdk-js/examples/?q=point+helper).

Here is the same dataset, but with point clustering enabled:

```js
import { helpers } from "@maptiler/sdk";

helpers.addPoint(map, {
  data: "public-schools.geojson",
  cluster: true,
});
```

On the other hand, if clusters are enabled, the default color is fueled by the color ramp `TURBO` scaled from `10` to `10000` non-linearly resampled with the method `"ease-out-square"`. The size also varies from `minPointradius` (default: `10`) to `maxPointRadius` (default: `50`):

![](./img/points-clustered.webp)

With the point helper, it’s also possible to adapt the color and the radius based on a property. In the following example, we display a point for each public school, with the scaling factor being the number of students:

```js
import { helpers } from "@maptiler/sdk";

helpers.addPoint(map, {
  data: "public-schools.geojson",
  property: "students",
  pointColor: ColorRampCollection.PORTLAND.scale(200, 2000).resample("ease-out-sqrt"),
  pointOpacity: 0.8,
  minPointRadius: 6,
  maxPointRadius: 30,
  showLabel: true,
  zoomCompensation: false,
})
```

![](./img/nyc-schools.webp)

Here, the `PORTLAND` color ramp is going to be used so that schools with `200` students or less will have the colors at the very begining of the color ramp and schools with `2000` or more will have the color defined at the very end. Schools in between will be attributed a colors in a non-linear fashion, following the `"ease-out-sqrt"` method (read [Color ramps](https://docs.maptiler.com/sdk-js/api/color-ramp/) section for more info).

View more [Point layer helper examples](https://docs.maptiler.com/sdk-js/examples/?q=point+helper).

## Heatmap layer helper

The heatmap layer is a great alternative for visualizing a collection of sparse data, but they can be challenging to use, especially when one has to come up with their own color ramp from scratch. **The helper makes this much easier!** Whenever it’s possible and it makes sense, we use the same terminology across the different helpers.

![](./img/heatmap-schools.webp)

### API reference

Here is a minimalist example, using the default built-in `TURBO` color ramp:

```js
import { helpers } from "@maptiler/sdk";

helpers.addHeatmap(map, {
  data: "public-schools.geojson",
});
```

[Function addHeatmap](https://docs.maptiler.com/sdk-js/api-reference/functions/addHeatmap/)

### Examples

Check out the full list of [examples](https://docs.maptiler.com/sdk-js/examples/?q=heatmap+helper).

Some visualisations are created with a fixed geographic extent or zoom level in mind, whether it’s a survey at the scale of a single neigbohood, or statitics at country scale. In this case, we want to tailor the color, radius, weight and intensity of the heatmap blobs exactely for this precise settings. In the following example, we disable the zoom compensation to make sure radii and intensity is never zoom-dependant:

```js
import { helpers } from "@maptiler/sdk";

helpers.addHeatmap(map, {
  data: "public-schools.geojson",
  property: "students",
  // radius: how wide are the blobs
  radius: [
    {propertyValue: 100, value: 15},
    {propertyValue: 800, value: 50},
  ],
  // weight: how intense are the blob, as fueled by a property
  weight: [
    {propertyValue: 100, value: 0.1},
    {propertyValue: 800, value: 1},
  ],
  // A custom color ramp, must be used with its default interval of [0, 1]
  colorRamp: ColorRampCollection.MAGMA,
  zoomCompensation: false,
  opacity: 0.6,
  // a global factor applied to all the blobs, regardless of the property or zoom
  intensity: 1.2,
});
```

![](./img/heatmap-colorramp.webp)

Turning off _zoom compensation_ allows for more accurate adjustments to the visualization at a specific zoom level, but it may not adapt as smoothly when zooming in or out.

View more [Heatmap layer helper examples](https://docs.maptiler.com/sdk-js/examples/?q=heatmap+helper).

## Take screenshot helper

The screenshot helper provides a quick and easy solution for capturing the current map view as a PNG image file, making it the most convenient way to save map snapshots.

Warning

Screenshots will not contain _DOM elements_ such as `Marker` and `Popup`, since those are not part of the rendering context.

### API reference

Here is a minimalist example to get a `blob` (PNG encoded):

```js
import { Map, helpers } from "@maptiler/sdk";

// ... initialize a Map instance, wait for the "load" or "ready" event ...

// Inside an async function, or with using .then()
const blob = await helpers.takeScreenshot(map);
```

[Function takeScreenshot](https://docs.maptiler.com/sdk-js/api-reference/functions/takeScreenshot/)

### Examples

Check out the full list of [examples](https://docs.maptiler.com/sdk-js/examples/?q=screenshot+helper).

There are two different ways to create screenshot, corresponding to two very different usecases. Note that screenshots will not contain _DOM elements_ such as `Marker` and `Popup`, since those are not part of the rendering context.

#### Get a `blob` of a screenshot, PNG encoded

```js
import { Map, helpers } from "@maptiler/sdk";

// ... initialize a Map instance, wait for the "load" or "ready" event ...

// Inside an async function, or with using .then()
const blob = await helpers.takeScreenshot(map);
```

The returned `blob` of a PNG image file can be very handy if the goal is to programmatically further manipulate the screenshot, such as sending it to some feedback endpoint with a POST request.

#### Download a PNG file

```js
import { Map, helpers } from "@maptiler/sdk";

// ... initialize a Map instance, wait for the "load" or "ready" event ...

// No need to be inside an async function, the download will be triggered when the file is ready
maptilersdk.helpers.takeScreenshot(map, {
  download: true, 
  filename: "map_screenshot.png"
});
```

Getting a file directly is a nice option that can be useful to share some debugging context with colleagues, compare multiple styles, or share your creation on social media.

Note

Keep in mind that MapTiler data are copyrighted and their usage is restricted. This include MapTiler built-in styles and tilesets, among others. In case of doubt, do not hesitate to read our [terms](https://www.maptiler.com/terms/) or to ask our [support team](https://www.maptiler.com/contacts/).

## Other helpers

### Convert GPX and KML to GeoJSON

In the [Polyline layer helper](#polyline) section above, we have seen that one can feed the helper directly with a path to a GPX or KML file, that is then converted under the hood client-side into a GeoJSON `FeatureCollection` object. This conversion feature is also exposed and can be used as such:

```js
import { gpx } from "@maptiler/sdk";

// ... assuming inside an async function

// Fetching the GPX file as a string:
const gpxFilePath = "some_gps_trace.gpx";
const gpxResponse = await fetch(gpxFilePath);
const gpxStr = await gpxResponse.text();

// Converting the GPX payload into a GeoJSON FeatureCollection:
const features = maptilersdk.gpx(gpxStr);
//or
const features = gpx(gpxStr);
```

And for KML files:

```js
import { kml } from "@maptiler/sdk";

// ... assuming inside an async function

// Fetching the KML file as a string:
const kmlFilePath = "some_gps_trace.kml";
const kmlResponse = await fetch(kmlFilePath);
const kmlStr = await kmlResponse.text();

// Converting the KML payload into a GeoJSON FeatureCollection:
const features = maptilersdk.kml(kmlStr);
//or
const features = kml(kmlStr);
```