Skip to main content

Mapbox

info
  • HTML tag name: <builderius-mapbox>
  • Implements 3rd-party script: Mapbox JS 2.10.0
  • Allowed children modules: none
  • Available since: 0.9.8 PRO

Description​

This module allows adding maps with markers, tracks or any other data visualization. It is an alternative to Google Maps. Using this module requires having an account on https://www.mapbox.com/ and using an API key.

How it works​

The module creates <builderius-mapbox> custom HTML tag. It is a modular self-contained instance of Mapbox GL JS library.

tip

Important: since <builderius-mapbox> is a custom HTML element, its default behavior is equal to inline element, not block; it can be changed any time with display CSS property in the module's settings.

This module requires adding Mapbox API key. This API key can be created on the account page on https://www.mapbox.com/. The registration is free and there are also 50000 free loads of the map. After we grab our API key we can use it inside the module via the data-api-key attribute.

By default, the map options are:

{
   center: [9.1496, 39.2561],
   zoom:   12,
   style:  'mapbox://styles/mapbox/streets-v11'
}

These options can be changed via data-settings attribute. With these default options the map will be loaded already.

Important: the coordinates must be defined in this order - first longitude, then latitude!

How to add a marker?​

Custom markers can be added to the map via data-markers attribute. Example:

[
    {
        "coord":[9.087933,40.070653],
        "desc":”Some description here”
    }
]

We add such a JSON array as the value of the mentioned before attribute and the map displays the marker.

API​

Attributes​

data-api-key (required)​

This attribute expects a string.

data-settings (required)​

This attribute expects a stringified JSON object with Mapbox options. The full list of available options is here: https://docs.mapbox.com/mapbox-gl-js/api/map/

data-fit-bounds-options (required)​

This attribute expects a stringified JSON object with Mapbox options. The full list is here: https://docs.mapbox.com/mapbox-gl-js/api/map/#map#fitbounds

data-markers (required)​

This attribute expects a stringified JSON array of data.

data-disable-scroll-zoom​

This attribute is a boolean type. Any value counts as true and also may be without a value - it also counts as true.

Events​

ready (scope: element)​

builderius-mapbox-ready (scope: window)​

This event is getting fired every time the component is being initiated/re-initiated. It also passes some data:

{ el, map, mapboxgl, getBoundingBox }

Where el is the reference to the HTML element. Where map is the reference to the Mapbox script instance. Where mapboxgl is the reference to the Mapbox library itself. Where getBoundingBox is the method of creating bounds object from the array of coordinates to be used in https://docs.mapbox.com/mapbox-gl-js/api/map/#map#fitbounds

loaded (scope: element)​

builderius-mapbox-loaded (scope: window)​

This event is getting fired just after the Mapbox script lifecycle even load https://docs.mapbox.com/mapbox-gl-js/api/map/#map.event:load is fired.

{ el, map, mapboxgl, getBoundingBox }

Where el is the reference to the HTML element. Where map is the reference to the Mapbox script instance. Where mapboxgl is the reference to the Mapbox library itself. Where getBoundingBox is the method of creating bounds object from the array of coordinates to be used in https://docs.mapbox.com/mapbox-gl-js/api/map/#map#fitbounds

Methods​

reInit​

This method resets and initiates the component.

Demo​

Demo page