> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/help/llms.txt) # Create a map style with custom data in Mapbox Studio This tutorial will walk you through creating a style with custom data, styling that data at different zoom levels, and adding that style to a [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/guides/) map so you can interact with its features. You will create this style in [Mapbox Studio](https://docs.mapbox.com/studio-manual/guides/), an in-browser style editor used to create custom map styles, which can then be passed into your web and mobile applications. You will learn how to: - Create a style with Mapbox Studio. - Import GeoJSON data and create a custom tileset. - Style circle and symbol layers. - Adjust the map style based on zoom level. - Publish your style. - Add the style in a web map. - Add hover and click interactivity to the symbol layer. Your final map will include markers showing several dog spas in Boston, MA, which you can click to show a [pop-up](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup) and see more information about the business: > **Note: Customizing the basemap** > > This tutorial covers adding and styling your custom data, displaying it above the default Mapbox Standard Style basemap. The basemap can be configured to change lighting, color themes, label visibility and more. To learn how to configure Mapbox Standard, see the [Configure the basemap tutorial](https://docs.mapbox.com/help/tutorials/configure-basemap-mapbox-studio/). ## Prerequisites There are two resources you will need to follow along with this guide: - **A Mapbox account:** Sign up for a free account on [Mapbox](https://account.mapbox.com/auth/signup/). - **A code editor**: A program like [Visual Studio Code](https://code.visualstudio.com/). ## Create your style In this step, you will create a new style using the Mapbox Standard basemap as a starting point. First, create a new map style in Mapbox Studio: 1. Open [Mapbox Studio](https://console.mapbox.com/studio/). - This will bring you to a list of styles from your account. 2. Click the **New style** button. - Your new style imports the Mapbox Standard Style, our premier global basemap. This basemap includes labels, water and land, buildings, and all the supporting visual features users expect to see on a map. The layers list is empty but will include your custom layers to be displayed above the basemap. To learn about configuration options for the basemap, see the [Configure the basemap tutorial](https://docs.mapbox.com/help/tutorials/configure-basemap-mapbox-studio/). 3. Leave the default settings and click the **Customize** button. 4. When the new window displays, hover over **Untitled** in the upper left corner of your browser and click on the pen icon to rename your style. - For example, rename the title to `Boston Dog Spas`. With your new style created, you are ready to import a custom dataset. Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/help/help/assets/medias/tutorials--add-data-to-a-style--new-style-6a6065dd71cea831c965eeeebca06edb.mp4). ## Create a new map layer and import data Now you will create a new layer and add the dog spa data to your style, using a GeoJSON file. GeoJSON is a format that encodes geographic data structures using JavaScript Object Notation (JSON). This format stores information in features—such as points, lines, polygons, etc. To learn more, go to the [GeoJSON](https://docs.mapbox.com/help/help/glossary/geojson/) glossary page. 1. First, download the example GeoJSON file by clicking the button below: [Download GeoJSON](https://docs.mapbox.com/help/help/data/dog-spas-boston.geojson) 2. Drag this GeoJSON file into Mapbox Studio. - Mapbox Studio will take the GeoJSON file, turn it into a [vector tileset](https://docs.mapbox.com/data/tilesets/guides/) and create a new layer based on the data. By default, Mapbox Studio will create a symbol layer from your data, creating a point and text element for each dog spa, adding a custom image and passing the business name into the text element. Any data you drag into Mapbox Studio will be analyzed and the layer type will be determined by the type of data you submit. Once the data has uploaded, the map view will be centered over Boston, MA, USA, displaying several markers across different dog spa locations. Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/help/help/assets/medias/tutorials--add-data-to-a-style--add-geojson-data-9082205cb2adec6f2fec6f765b33c192.mp4). With your custom dataset loaded and added to the map, you're ready to add more complex and visually appealing layers to visualize the dog spas. ## Add zoom-dependent layers to style your data In the previous step, you added data to a layer in your style, which created a symbol layer. Now you'll replace this layer with two layers that work together to create a more polished, responsive experience — each optimized for one end of the zoom spectrum. At low zoom levels (0-11), you will render circles over each point to give the user a general sense of where dog spas are located. At high zoom levels (11-22), you will render markers with custom images to help each dog spa stand out as more features of the map become visible — buildings, street names and more. ![Circle layer transitioning to marker layer after zoom level 11](https://docs.mapbox.com/help/assets/ideal-img/tutorials--add-data-to-a-style--circles-to-markers.480.gif) These two layers will fade smoothly between one another as the user zooms to create a seamless experience. By the end of this section, your map will show circles when zoomed out and markers when zoomed in. ### Step 1: Style your symbol layer Symbol layers allow you to add custom images and text to your map. You will change your layer to make the data visible from zoom levels `11`–`22` and show a custom marker for each dog spa when the user is zoomed in. 1. In the layer's **Style** tab, double-click the layer name and rename it `dog-spas-markers`. 2. Open the **Select data** tab on your new layer. 3. Click **Zoom extent** and set **Min** to `11` and **Max** to `22`. - This hides the marker layer at lower zoom levels so you only see the text labels when you're zoomed into the map. 4. Go back to the **Style** tab and choose **Icon** at the top of the panel. - This switches the symbol layer configuration so you can add a custom image for the markers. 5. Download the image for the custom marker by clicking the button below: [Download SVG](https://docs.mapbox.com/help/help/data/dog-spa-marker.svg) 6. Upload the custom image for the marker. - In the Style tab in the **Image**, under the grid, select **Add or remove images**. - In the new window that appears, click **Upload images** and drag in the `dog-spa-marker.svg` you downloaded. - After the `svg` uploads, click **Confirm** and then select the image from the grid. This will be a blue marker icon with a paw. - Click **Size** and set the image size to `0.75`, to make the marker more visible. - Make sure you are zoomed in on the map; otherwise you may not see the new markers. 7. Next, change the marker overlap settings so all markers render: - By default, Mapbox Studio prevents icons from overlapping to optimize large datasets. For this small dataset, enable overlap so all markers display. - Click on the **Placement** towards the top of the panel. - Then, scroll to the bottom of the settings options, click on **Allow icon overlap** and set the toggle to `true`. 8. Style the text labels for readability: - Select the **Text** tab at the top of the **Style** panel. - Click on **Color**, scroll down to the bottom of the panel and click `Clear value` - In the new color swatch, set the `HEX` value to `#4065dd`. - Click **Font** and choose `Poppins ExtraBold`. - Click **Size** and set the font size to `12`. - Open the **Position** tab and set **Text Offset** `y` to `1`. 9. Change the settings to prevent overlap, like you did with the markers. - Open the **Placement** tab and scroll down to the bottom. - Click on **Allow text overlap** and set the toggle to `true`. The markers will now appear at zoom level 11 and overlap as needed to show all locations. Next, you will create a circle layer to represent the dog spas at lower zoom levels. Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/help/help/assets/medias/tutorials--add-data-to-a-style--style-markers-0121a85f596c60d7cd503ad71eb8ce44.mp4). ### Step 2: Create and style a circle layer Next you will create a circle layer that will be visible from zoom levels `0`–`11`, render small circles at each dog spa, and stop rendering these circles at lower zoom levels where the symbol layer is being rendered. 1. Duplicate the `dog-spas-markers` layer and rename it `dog-spas-circles`. 2. Next, inside the new layer tab, click on **Select Data** in the top right corner. 3. Click on **Type** and select **Circle** from the options. 4. In the pop-up, select **Discard Styling**. - This will add circles to your map over each of the dog spas — rendering elements over each point, making the data easier to view at lower zoom levels. 5. Next, set the **Min** zoom extent to `0` and the **Max** zoom extent to `11`. - This will only allow the circles to render at lower zoom levels before transitioning into the symbol layer. 6. Next, go back to the **Styles** tab and select **Color**. 7. Scroll down, click `Clear value` and set the color to `#4065dd`. Now at lower zoom levels you will see a set of blue circles rendered over each dog spa. As you zoom further in, the style will switch to a symbol layer with custom images and text over each dog spa. You can edit this layer further, if you choose, changing the radius, stroke, etc. Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/help/help/assets/medias/tutorials--add-data-to-a-style--style-circle-layer-4b1927fe84af1d7a218fd9335e0dacad.mp4). Now that you've adjusted your style, in the next step you will learn how to publish your changes. ## Publish your style To use your style in a web or mobile application, you will need to publish your style and access the share URL: 1. Click **Publish** in the top-right corner to open the publishing menu. - The menu shows a side-by-side comparison of the original (previous) version and your current edits. 2. If you're satisfied with the changes, click the **Publish** button at the bottom of the window. 3. After publishing, click **Share** in the top toolbar to view share options. 4. In the new window that appears, scroll down to Developer resources and click on **Web**. 5. Click the copy button next to **Style URL**. You can use this URL in your mobile apps and websites to display your style in a Mapbox map. The style URL looks like this: ``` mapbox://styles/{username}/{styleid} ``` Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/help/help/assets/medias/tutorials--add-data-to-a-style--publish-your-style-63dc79ba6ebb24d3fae3da69deb8536e.mp4). Now that you've created your style, the optional section below walks through adding the style to a web map and enabling interactivity for the point features. ## (Optional) Add your style to a map and add interactivity In this optional step, you will use your custom style in a Mapbox GL JS web map, and add hover and click interactions to display a [pop-up](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup) with details about each feature. If you would instead like to implement this style into a mobile app, the same concepts are covered for iOS and Android apps in these tutorials: > **Related content (tutorial): [Build an iOS marker app from a custom style and tileset](https://docs.mapbox.com/help/help/tutorials/ios-marker-app-custom-style/)** > > Learn how to build an iOS app that displays a map with a custom style, tileset and custom markers. > **Related content (tutorial): [Build an Android marker app from a custom style and tileset](https://docs.mapbox.com/help/help/tutorials/android-marker-app-custom-style/)** > > Learn how to build an Android app that displays a map with a custom style, tileset and custom markers. Otherwise, continue with this tutorial for the web version. ### Step 1: Add the map with your style You will need to add a map to your web application and add references to your access token and the Style URL from the style you created. 1. Copy and paste the code below into an HTML file. ```html Add and style data in Mapbox Studio
``` 2. Replace `YOUR_MAPBOX_ACCESS_TOKEN` with an access token from your [Mapbox Console](https://console.mapbox.com). 3. Replace 'YOUR_STYLE_URL' with the style URL you created in the [publish your style step](#publish-your-style). Now if you save and refresh the page, you should be able to see the markers plotted across the map. > **Note (warning): Troubleshooting** > > If you add the style URL and do not see your markers, check the following: > > - You're using an access token from the same account that owns the style. > - You have published the style. > - You have waited a few minutes after publishing and refreshed the page. It can take a few minutes for the Style URL to become available. ### Step 2: Add interactions to the map markers Now that you have a map with your style, you can use [`addInteraction()`](https://docs.mapbox.com/mapbox-gl-js/guides/user-interactions/interactions/#adding-an-interaction-to-a-map-layer) to add functionality to each of your layers. You will add a pop-up that appears when the user clicks a marker — containing information from the related GeoJSON data — and change the cursor when the user hovers over a marker. Add the following code above the bottom `` tag to add the Interactions API on each layer. This allows the map to detect when the user hovers over or clicks on a point feature on both the circle and symbol layers and then displays a pop-up using the location of the selected point feature. The pop-up then retrieves the related data from the GeoJSON file and updates the text with the information, such as the business name, address and phone number. ```js // Our custom layers const layers = [ 'dog-spas-markers', 'dog-spas-circles'] // Iterate over each layer and add our interactions layers.forEach((layer, index) => { // Add Click interaction map.addInteraction(`click-marker-${index}`, { type: 'click', target: { layerId: layer }, handler: (e) => { const popup = new mapboxgl.Popup({ offset: [0, -15] }) .setLngLat(e.feature.geometry.coordinates) .setHTML( `

${e.feature.properties.storeName}

${e.feature.properties.address}

${e.feature.properties.phoneFormatted}

` ) .addTo(map); } }); // Add mouse-enter interaction map.addInteraction(`mouse-enter-marker-${index}`, { type: 'mouseenter', target: { layerId: layer }, handler: (e) => { console.log(map.style.cursor); map.getCanvas().style.cursor = 'pointer'; } }); map.addInteraction(`mouse-leave-marker-${index}`, { type: 'mouseleave', target: { layerId: layer }, handler: (e) => { map.getCanvas().style.cursor = ''; } }); }) ``` Now, when you hover over points, the cursor will change, and when you click a marker, the pop-up will appear with the point feature information. ### Final code The code snippet below shows the final version of the code with all the interactivity added. ```html Display a map on a webpage
``` ## Next steps **Congratulations!** 🎉 You have added custom data to a style, added that style to a map and added interactivity to your data layer. ### Final map ### What was covered - Create a style with Mapbox Studio. - Import GeoJSON data and create a Mapbox tileset. - Style circle and symbol layers. - Adjust the map style based on zoom level. - Publish your style. - Add the style to a map. - Add interactivity to the markers. ### Learn more Below are more helpful tutorials to follow: - [Creating a custom style](https://docs.mapbox.com/help/tutorials/create-a-custom-style/) - [Creating Interactive Hover Effects](https://docs.mapbox.com/help/help/tutorials/create-interactive-hover-effects-with-mapbox-gl-js/) - [Build a store locator](https://docs.mapbox.com/help/help/tutorials/building-a-store-locator/)