Squarespace X Mapbox

How to Add an Interactive Mapbox Map to Your Squarespace Website

This guide shows developers how to integrate Mapbox GL JS into a Squarespace website using Squarespace's embed block. If you're already familiar with Mapbox GL JS development and want to add custom interactive maps to your Squarespace site, this post will show you exactly where to place your code to get it working.

✅ What this guide covers: The technical steps to embed Mapbox GL JS code in a Squarespace website
❌ What this guide doesn't cover: Details of interactive map development with Mapbox GL JS (the examples are a great place to start for inspiration and working code snippets)

We'll show a simple example of displaying a business location with a marker, popup, and rotating camera to demonstrate the integration. Once you understand where the code goes and how it's structured in Squarespace, you can implement any Mapbox GL JS functionality you need by changing the JavaScript code.

Here's a codepen so you can get a better look at the actual map and animation shown in this guide. It uses the Mapbox Standard Style as a basemap, showing detailed 3D buildings and an optional monochrome theme. The popup is styled to match the green colors used on the Squarespace site it is embedded in:

Note: This technique of adding custom HTML, CSS and JavaScript via the Squarespace editor is suitable for simpler Mapbox GL JS implementations but does not include version control or other benefits of a separate development workflow. If your map becomes more complex, you may want to deploy it as a standalone web app, then embed it in your Squarespace site using its URL.

Prerequisites

To follow this guide, you'll need:

• A Squarespace website
• Working knowledge of Mapbox GL JS - you should be comfortable writing HTML, CSS, and JavaScript to create maps
• A Mapbox account and access token - if you don't have one yet, sign up here

Getting Your Mapbox Access Token

Before we start, you'll need a Mapbox access token:

1. Go to mapbox.com and sign up for a free account (if you don't have one)
2. Once logged in, navigate to your console
3. Find the "Tokens" link in the left sidebar to go to the tokens page
4. Copy your default public token (it starts with pk.)

Keep this token handy—you'll need it in a moment.

Step 1: Adding the Code Block

Let's add the HTML that will contain your map code:

1. Open your Squarespace Editor and navigate to the page where you want to add the map
2. Click the + ADD BLOCK button
3. Scroll down in the block selection panel to find "Embed"
4. Drag and resize the embed block to position it wherever you want it on your site layout.
5. Double-click on the embed block to open its Content settings panel. Under EMBED AS, choose Code Snippet, then click the Embed Data button.
6. A code editor will appear. You will add code to this input in the next step.

Step 2: Add Mapbox GL JS Code

Now you'll add Mapbox GL JS code to get a map working in the code block. The code block accepts any HTML, so you can include CSS and JavaScript by using <style> and <script> tags.

Here's a working example that shows a business location with a marker and rotating camera. Copy this code and replace YOUR_MAPBOX_ACCESS_TOKEN with your actual access token:

<!-- import Mapbox GL JS and its CSS file -->
<script src='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.css' rel='stylesheet' />

<!-- override default styles for the map and popup -->
<style>
  .mapboxgl-popup-content {
    background-color: #e6f2d2;
    color: #2f5f48;
  }
</style>

<!-- add a container element for the map -->
<div id="map-container" style="position: absolute; height: 100%; width: 100%"></div>

<script>
  // your Mapbox access token
  mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

  // initialize the map
  const map = new mapboxgl.Map({
    container: 'map-container', // container ID
    style: 'mapbox://styles/mapbox/standard', // style URL
    center: [-73.99986, 40.75300], // starting position [lng, lat]
    zoom: 15.36, // starting zoom
    bearing: 28.00, // bearing in degrees
    pitch: 56.50, // pitch in degrees
    config: {
      basemap: {
        theme: 'monochrome', // use the monochrome basemap theme
        showPointOfInterestLabels: false // hide point of interest labels
      }
    }
  });

  // disable scroll zoom so the map won't zoom as the user scrolls down the page
  map.scrollZoom.disable();

  // create a popup with address details and a link to get directions on Google Maps
  const popup = new mapboxgl.Popup({
    closeOnClick: false,
    closeButton: false,
    offset: 40,
  }).setHTML(
    `<div>
      450 W 33rd St<br/>
      New York, NY 10001</div>
      <a href="https://maps.app.goo.gl/6WzErvMBMi2Hn64Z7" target="_blank" rel="noopener noreferrer"><span class="text-xs">Get Directions</span></a>
    `
  );

  // create a map marker with a custom color, connect the popup, add it to the map, and open the popup
  new mapboxgl.Marker({
    color: '#2f5f48'
  })
    .setLngLat([-73.99986, 40.75300])
    .setPopup(popup)
    .addTo(map)
    .togglePopup();

  // this function rotates the camera continuously
  // see https://docs.mapbox.com/mapbox-gl-js/example/animate-camera-around-point/
  function rotateCamera(timestamp) {
    map.rotateTo((timestamp / 200) % 360, { duration: 0 });
    requestAnimationFrame(rotateCamera);
  }

  map.on('load', () => {
    // start the camera animation.
    rotateCamera(0);
  })
</script>

Paste the Mapbox GL JS snippet from above into the code editor.

Important: Replace the placeholder text YOUR_MAPBOX_ACCESS_TOKEN with the actual token you copied from your Mapbox account.

Click anywhere outside the editor panel to apply your code update. You will see a warning about embedded scripts, with an option to preview in safe mode. This is normal, as Squarespace prevents execution of JavaScript code in the editor by default.

Exit the editor. You should see an animated map with a monochrome basemap, a marker centered over New York City, and a slowly rotating camera. That's it, you're ready to publish this map on your site!

Understanding the Code Structure

Here's how the code for this example map breaks down:

1. Library Imports

<script src='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.css' rel='stylesheet' />

These load Mapbox GL JS and its required stylesheet from the Mapbox CDN.

2. Custom Styles

<style>
  .mapboxgl-popup-content {
    background-color: #e6f2d2;
    color: #2f5f48;
  }
</style>

The popup styles customize the appearance to match the page theme.

3. Map Container

<div id="map-container" style="position: absolute; height: 100%; width: 100%"></div>

This div is where the map renders. The inline styles ensure it fills the available space.

4. Your Map Logic

<script>
  // All your Mapbox GL JS code goes here
</script>

This is where you implement your map functionality. In this example, we're:

• Setting the access token
• Initializing the map with specific style and camera settings
• Disabling scroll zoom (important for Squarespace pages!)
• Creating a popup and marker
• Adding a camera rotation animation

You can replace or extend this code with any Mapbox GL JS functionality you need.

If you want to adapt this example of a single marker and popup, you should:

• Change the map's center point, zoom, pitch and bearing to your desired initial camera view.
• Change the Marker's coordinates
• Change the Popup's content by editing the HTML code in Popup.setHTML()

Or, you can leave the imports and the map container in place and start over with the map JavaScript code and build whatever you need. See additional developer resources below.

Resources for Mapbox GL JS Development

Here are essential resources for building your map functionality:

Mapbox Documentation

• Mapbox GL JS Examples - Dozens of live, interactive code examples
• Mapbox GL JS Guides
• Mapbox GL JS API Reference - Complete documentation of all map methods and options

Key Examples

• Display a map - Basic map initialization
• Add markers to a map - Working with markers
• Display a popup - Popup functionality
• Add GeoJSON data - Display custom data

Community

• r/mapbox on Reddit - Get help and share ideas
• Mapbox Developer Discord - Post in the #web channel to ask questions and share what you build.

Troubleshooting

Map not displaying?

• Verify you've replaced YOUR_MAPBOX_ACCESS_TOKEN with your actual token
• Check that your access token has the correct permissions
• Ensure the code block has sufficient height and width in the Squarespace editor and that the map container div also has sufficient height and width
• Open your browser's developer console to check for JavaScript errors

---

By following the steps in this guide, you should now have a Mapbox GL JS map working in your Squarespace website and are ready to iterate the JavaScript code to customize the map to meet your needs.

Questions about this integration approach? Found a better way to do something? Share your experience in the comments!