Skip to main content

Map styles

With Atlas, you can use default Mapbox map styles or use a custom map style created in Mapbox Studio.

Mapbox map styles​

Atlas includes default Mapbox styles in the /data/styles/mapbox directory. You can use these styles out-of-the-box or customize them:


To use one of these styles, update the style parameter in the Mapbox GL JS Map class to the path of the style.json file in the /data/styles/mapbox directory:

const map = new mapboxgl.Map({
  container: 'map',
  // Use HTTP or HTTPS
  style: 'http://<your-atlas-url>/data/styles/mapbox/streets-v12.json',
  center: [-74.5, 40],
  zoom: 9
});

You will also need to update the URLs for sprite, glyphs, and sources to point to your Atlas deployment and Atlas tilesets. For an example, see set up the Streets v12 style in the get started guide.

Custom map styles​

If you want to use a custom map style, you must author your styles on mapbox.com Studio, export the custom style files, and host them in your Atlas v3 deployment.

Standard style is not supported
Atlas does not yet support the Mapbox Standard style. Only classic Mapbox styles are compatible with Atlas. When creating a custom map style for Atlas, always select a classic style.

1. Select a classic Mapbox map style​

First, pick a classic Mapbox map style that most aligns with the vision for your custom map style.

Once you've picked a style, click on + Add to your Studio in the classic Mapbox map style guide to automatically add the classic map style to your Mapbox.com account.

2. Create a secret access token for the Styles API​

Create a Mapbox secret access token with the styles:list, styles:download, and fonts:list scopes. You will use this access token in step 4 to download additional sprites files.

3. Download the style bundle​

There are two ways to download your custom map style: via the Studio UI or programmatically via the Styles API.

Option A — Studio UI

  1. Open your custom style in Studio
  2. Click Share in the upper menu.
  3. Scroll to the bottom of the share panel and click the Download link.

The download is a zip file with the following directory structure:

<style-name>/
├── fonts/
│   └── *.ttf
├── sprites/
│   └── *.svg
└── style.json

Option B — Styles API

Using the secret access token you created in step 2, run the following commands:

# Download the style bundle for a published style
curl "https://api.mapbox.com/styles/v1/{username}/{style_id}.zip?access_token={YOUR_SECRET_MAPBOX_ACCESS_TOKEN}" \
  -o my-style.zip

# Download the style bundle for a draft style
curl "https://api.mapbox.com/styles/v1/{username}/{style_id}/draft.zip?access_token={YOUR_SECRET_MAPBOX_ACCESS_TOKEN}" \
  -o my-style-draft.zip

4. Download the full sprite images and JSON files​

While the style bundle includes SVG sprite icons, we still need to download the full sprite PNG images (default and @2x) and sprite JSON files using the Mapbox Styles API.

Run the following commands:

# Request the sprite image as a PNG
curl "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/STYLE_ID/sprite.png?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"

curl "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/STYLE_ID/sprite@2x.png?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"

# Request JSON for a sprite
curl "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/STYLE_ID/sprite?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"

curl "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/STYLE_ID/sprite@2x?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"

5. Move the style files to your Atlas deployment​

The final step is to move all the downloaded custom map style files to your Atlas deployment. We recommend moving fonts to /data/fonts, sprites to /data/sprites, and style.json files to /data/styles.

You will also need to edit the style.json file for your custom map style with the URLs for your sprites, fonts, and tilesets. For an example, see set up the Streets v12 style in the get started guide.

  • sprite — Update your sprite files path (e.g., /data/sprites)
  • glyphs — Update to your fonts path (e.g., /data/fonts)
  • sources — Update to your tilesets path (e.g., /data/tilesets)
Was this page helpful?