How to implement Mapbox GL JS with a custom Gutenberg block in FSE?

Question

I'm working on a custom Gutenberg block that uses the Mapbox GL JS API for displaying a map. To create the map I have to call the following constructor.

const map = new mapboxgl.Map({
  container: 'map', // container ID
  style: 'mapbox://styles/mapbox/streets-v12', // style URL
  center: [-74.5, 40], // starting position [lng, lat]
  zoom: 9 // starting zoom
});

According to the documentation, the container property can be either a string with the ID of the container or an instance of an HTMLElement. Since my implementation is a Gutenberg block, I went with the latter by using useRef from the @wordpress/element package to reference the container element.

The following code is my implementation:

import mapboxgl from 'mapbox-gl';
import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import { useEffect, useRef, useState } from '@wordpress/element';

mapboxgl.accessToken = '*myaccesstoken*';

const Edit = ({ attributes, setAttributes }) => {
  const blockProps = useBlockProps();

  const mapContainer = useRef(null);
  const mapRef = useRef(null);
  const [lng, setLng] = useState(-70.9);
  const [lat, setLat] = useState(42.35);

  useEffect(() => {
    if (mapRef.current !== null || mapContainer.current === null) {
      return;
    }

    mapRef.current = new mapboxgl.Map({
      container: mapContainer.current,
      style: 'mapbox://styles/mapbox/streets-v12',
      center: [lng, lat],
      zoom: 9
    });
  }, []);

  return (
    <div {...blockProps}>
      <div id="map" ref={mapContainer}></div>;
    </div>
  )
};

export default Edit;

Whenever I use this block in the Full Site Editing (FSE) mode, the mapboxgl.Map constructor throws the following error:

Error: Invalid type: 'container' must be a String or HTMLElement.

(This doesn't happen whenever the block is used on a single post).

When logging mapContainer.current I can see the <div #map> element being logged, though the constructor is not accepting it. Is the element referenced in useRef somehow not an actual HTMLElement instance?

I based my implementation on this Mapbox + React tutorial from their own site.

Selecting a random element outside the block with the DOM API does work as expected. For example container: document.getElementById('some-id'). This does indicate that the API works.

Selecting the <div #map> from within the useEffect hook with the DOM API results in the element not being found.

container: 'map' // -> Error: Container 'map' not found

container: document.getElementById('map') // -> Error: Invalid type: 'container' must be a String or HTMLElement

Github repo of block

Answer 1

Is the element referenced in useRef somehow not an actual HTMLElement instance?

No, it is.

But (as you've already known it), Mapbox GL JS ^(v2.15.0) requires that the container, when supplied as an element, be an instance of window.HTMLElement. ( note the window. which means the parent window )

And the thing is, on the FSE/Site editor page, the block's editor script which initializes the Mapbox map is in the parent window, but then div#map is inside a child window which is an iframe named editor-canvas, hence:

1. document.getElementById('map'), where document refers to window.document, returned a null.

2. The map div is no longer an instance of window.HTMLElement and instead, it's now an instance of the iframe's contentWindow.HTMLElement. I.e.

   • mapContainer.current instanceof HTMLElement (which is the same as mapContainer.current instanceof window.HTMLElement) returns false.

   • mapContainer.current instanceof document.querySelector( 'iframe[name="editor-canvas"]' ).contentWindow.HTMLElement returns true.

So for the time being, as you commented, you would need to use SSR (i.e. server-side rendering) instead.

I've created a GitHub repo with a working example where my edit function returns an element with an iframe which renders the Mapbox map, as you could see below: (I used Firefox)

And here's my edit function: ( see full code here )

const Edit = ( { attributes, setAttributes } ) => {
    const { accessToken } = attributes;

    const mapContainer = useRef( null );

    const [ mapLoaded, setMapLoaded ] = useState( false );

    const onMapFrameLoad = () => {
        let map;

        // Note: getMap is defined on the SSR page. It's a custom function which
        // returns the Mapbox instance for the map initialized on that SSR page.
        try {
            map = mapContainer.current.contentWindow.getMap();
        } catch ( error ) {
            console.log( 'Error accessing the Mapbox\'s map instance!', error );
            return;
        }

        map.on( 'load', () => {
            setMapLoaded( true );
            console.log( 'map ready', map );
        } );
    };

    return (
        <div { ...useBlockProps() }>
            { /* In this demo, I'm deliberately not using <InspectorControls>. */ }
            <fieldset>
                <TextControl
                    label="Access Token"
                    value={ accessToken }
                    onChange={ ( value ) => setAttributes( { accessToken: value } ) }
                />
            </fieldset>

            { ( accessToken && ! mapLoaded ) && <i>Loading map..</i> }

            { accessToken && (
                <iframe
                    src={ ssrPageUrl( accessToken, 300 ) }
                    width="100%"
                    height="300"
                    style={ { border: 0, overflow: 'hidden' } }
                    id="map-frame"
                    onLoad={ onMapFrameLoad }
                    ref={ mapContainer }
                ></iframe>
            ) }
        </div>
    );
};

Answer 2

Thanks to the very helpful answer of @sally-cj we found out that Mapbox requires the container property to be an instance of window.HTMLElement or a valid string to query for an element. Because of the structure of the FSE environment, some browsers, like Firefox^117.0b5, will not evaluate instanceof window.HTMLElement to true. This will result in the map throwing the following error.

Error: Invalid type: 'container' must be a String or HTMLElement.

As a solution we can wrap the creation of mapboxgl.Map in a custom element with a shadow DOM. This way we can reference the container element from within the custom element, and because the element is in the shadow DOM, it will always be an instance of window.HTMLElement.

A implementation of a custom element would look like the snippet below.

custom-element.js

This snippet will register the custom element as a mapbox-map HTML element. The mapboxgl.Map will run in the connectedCallback. It will fire a CustomEvent when the map loads which enables us to listen outside of the custom element for the load event.

import mapboxgl from 'mapbox-gl';

class MapboxElement extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = `
      <link href='https://api.mapbox.com/mapbox-gl-js/v2.15.0/mapbox-gl.css' rel='stylesheet' />

      <style>
        :host {
          contain: layout;
          display: block;
          position: relative;
          width: 100%;
        }

        #container {
          display: block;
          height: 100%;
          width: 100%;
        }
      </style>

      <div id="container"></div>
    `;
  }

  get container() {
    return this.shadowRoot.querySelector('#container');
  }

  get accessToken() {
    return this.getAttribute('access-token');
  }

  set accessToken(value) {
    if ('string' === typeof value) {
      this.setAttribute('access-token', value);
    } else {
      this.removeAttribute('access-token');
    }
  }

  connectedCallback() {
    const map = new mapboxgl.Map({
      accessToken: this.accessToken,
      container: this.container
    });

    map.on('load', () => {
      const mapReadyEvent = new CustomEvent('mapready', {
        bubbles: true,
        detail: {
          map
        }
      });

      this.dispatchEvent(mapReadyEvent);
    });
  }
}

customElements.define('mapbox-map', MapboxElement);

Edit.js

Here we render the mapbox-map element whenever the accessToken value isn't empty. It then adds an event listener to the custom element to set the isLoaded state whenever the map has been loaded.

The event will also expose the mapboxgl.Map instance in the detail property of the CustomEvent.

import { useEffect, useRef, useState } from '@wordpress/element';

const Edit = ({ attributes, setAttributes }) => {
  const { accessToken } = attributes;
  const [isLoaded, setIsLoaded] = useState(false);
  const blockProps = useBlockProps();
  const mapRef = useRef(null);

  useEffect(() => {
    if (!accessToken) {
      return;
    }

    setIsLoaded(false);

    mapRef.current.addEventListener('mapready', (event) => {
      const map = event.detail.map;
      // ... Use the map here.

      setIsLoaded(true);
    });
  }, [accessToken]);

  return (
    <div {...blockProps}>
      {accessToken && (
        <mapbox-map
          ref={mapRef}
          access-token={accessToken}
        ></mapbox-map>
      )}
    </div>
  );
}

block.json

To load the custom element into both the FSE and frontend, add the script property and reference the custom-element.js file.

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "domain/mapbox-map",
  "title": "Mapbox Map",
  "version": "1.0.0",
  "editorScript": "file:./index.js",
  "script": "file:./custom-element.js",
  ...
}