Change a map's worldview | Mapbox GL JS

This example shows how to specify a worldview when creating a map and how to change worldviews dynamically after a map has been created. Worldviews are used to change map features to fit the context of various regional, cultural, or political groups.

The map is instantiated using the worldview option, explicitly setting the worldview to United States (US). When the user clicks a worldview button, Map.setWorldview() is called to update the map's worldview.

To see a full list of supported worldviews, see the Internationalization and Localization guide.

JavaScript

React

JavaScript

React


<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Change a map's worldview</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.24.0/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.24.0/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<style>
    #buttons {
        width: 90%;
        margin: 0 auto;
        display: flex;
        justify-content: center;
        gap: 10px;
    }

    .button {
        display: inline-block;
        position: relative;
        cursor: pointer;
        width: 20%;
        padding: 8px;
        border: none;
        border-radius: 3px;
        margin-top: 10px;
        font-size: 12px;
        text-align: center;
        color: #fff;
        background: #ee8a65;
        font-family: sans-serif;
        font-weight: bold;
    }

    .button.active {
        background: #c45f38;
    }
</style>
<div id="map"></div>
<div id="buttons">
    <button id="button-CN" class="button">China (<code>CN</code>)</button>
    <button id="button-IN" class="button">India (<code>IN</code>)</button>
    <button id="button-JP" class="button">Japan (<code>JP</code>)</button>
    <button id="button-US" class="button active">
        United States (<code>US</code>)
    </button>
</div>
<script>
    const map = new mapboxgl.Map({
        // TO MAKE THE MAP APPEAR YOU MUST
        // ADD YOUR ACCESS TOKEN FROM
        // https://account.mapbox.com
        accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
        container: 'map',
        // Choose from Mapbox's core styles, or make your own style with Mapbox Studio
        style: 'mapbox://styles/mapbox/standard',
        center: [94.70827, 28.40298],
        zoom: 6.1,
        worldview: 'US'
    });

    document.getElementById('buttons').addEventListener('click', (event) => {
        const worldview = event.target.id.substr('button-'.length);
        // Use setWorldview to switch the map's worldview.
        map.setWorldview(worldview);
        document
            .querySelectorAll('.button')
            .forEach((btn) => btn.classList.remove('active'));
        event.target.classList.add('active');
    });
</script>

</body>
</html>

This code snippet will not work as expected until you replace YOUR_MAPBOX_ACCESS_TOKEN with an access token from your Mapbox account.

JavaScript

React


import React, { useEffect, useRef, useState } from 'react';
import mapboxgl from 'mapbox-gl';

import 'mapbox-gl/dist/mapbox-gl.css';

const buttonStyle = {
  display: 'inline-block',
  position: 'relative',
  cursor: 'pointer',
  width: '20%',
  padding: '8px',
  border: 'none',
  borderRadius: '3px',
  marginTop: '10px',
  fontSize: '12px',
  textAlign: 'center',
  color: '#fff',
  background: '#ee8a65',
  fontFamily: 'sans-serif',
  fontWeight: 'bold'
};

const worldviews = [
  { code: 'CN', label: 'China' },
  { code: 'IN', label: 'India' },
  { code: 'JP', label: 'Japan' },
  { code: 'US', label: 'United States' }
];

const activeButtonStyle = {
  background: '#c45f38'
};

const MapboxExample = () => {
  const mapContainerRef = useRef(null);
  const mapRef = useRef(null);
  const [activeWorldview, setActiveWorldview] = useState('US');

  useEffect(() => {
    mapRef.current = new mapboxgl.Map({
      // TO MAKE THE MAP APPEAR YOU MUST
      // ADD YOUR ACCESS TOKEN FROM
      // https://account.mapbox.com
      accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
      container: mapContainerRef.current,
      // Choose from Mapbox's core styles, or make your own style with Mapbox Studio
      style: 'mapbox://styles/mapbox/standard',
      center: [88, 26],
      zoom: 4,
      worldview: 'US'
    });

    return () => mapRef.current.remove();
  }, []);

  const handleClick = (worldviewCode) => {
    // Use setWorldview to switch the map's worldview.
    mapRef.current.setWorldview(worldviewCode);
    setActiveWorldview(worldviewCode);
  };

  return (
    <div style={{ height: '100%', position: 'relative' }}>
      <div ref={mapContainerRef} id="map" style={{ height: '100%' }} />
      <div
        id="buttons"
        style={{
          position: 'absolute',
          top: 0,
          width: '90%',
          left: '5%',
          display: 'flex',
          justifyContent: 'center',
          gap: '10px'
        }}
      >
        {worldviews.map(({ code, label }) => (
          <button
            key={code}
            style={{
              ...buttonStyle,
              ...(activeWorldview === code && activeButtonStyle)
            }}
            onClick={() => handleClick(code)}
          >
            {label} (<code>{code}</code>)
          </button>
        ))}
      </div>
    </div>
  );
};

export default MapboxExample;

This code snippet will not work as expected until you replace YOUR_MAPBOX_ACCESS_TOKEN with an access token from your Mapbox account.

Was this example helpful?