Basic Map Management

Everything starts here. In order to apply a chain of customizations, you must first create a map object using the map method, or retrieve an existing map object using the getMap method.

Once you've got a map object, you will be able to apply any of the Universal Methods available.

Chainable Map Object

Both of these methods return a chainable map object. This makes it possible to string together as many of the following methods as needed, in any order you prefer.

Each language has a special command for rendering the map, and thus ending the chain. Make note of how to end the chain for whichever language you are working in.

# map(locations, options)

Use the map method to create a new map object.

const map =, options);


  • locations (locations) - Will be used to create markers for the map.
  • options (array|null) - The options parameter allows you to configure the map in greater detail.

Available Options

Most (though not all) of these options are available across JavaScript, Twig, and PHP. Please note the few options which are not universally available.

# Dynamic Map Options

Option Available Description
id JS/Twig/PHP Set the id attribute of the map container.
width JS/Twig/PHP Set the width of the map (in px).
height JS/Twig/PHP Set the height of the map (in px).
zoom JS/Twig/PHP Set the default zoom level of the map. (1-22)
center JS/Twig/PHP Set the center position of the map.
style JS/Twig/PHP A string or object declaring the map style.
mapOptions JS/Twig/PHP Accepts any Map parameters (opens new window).
markerOptions JS/Twig/PHP Accepts any Marker parameters (opens new window)
popupOptions JS/Twig/PHP Accepts any Popup parameters (opens new window)
popupTemplate Twig/PHP Template path to use for creating popups.
field Twig/PHP Address field(s) to be included on the map. (includes all by default)

Additional Details

For more info, please consult either the JavaScript method or the Twig/PHP constructor.

# getMap(mapId)

Retrieve an existing map object. The mapId value would have been set when the map was originally created. If no ID was specified at the time of creation, the map will have a randomly generated ID.

const map = mapbox.getMap(mapId);


  • mapId (string) - The ID of the map that you want to access.