Docs / Setup / React / Mapbox

Mapbox setup

How to use Mapbox on the Web through MapConductor. The access token is only needed for Mapbox-hosted styles — the ones starting with mapbox://.

PACKAGE

react-for-mapbox

API KEY

Style-dependent

CSS

Required

REACT NATIVE

None

Same provider, other platformsAndroid iOS

View demoStore Map · React ↗

Before you start

Node.js 18 or newer

A public access token, if you use Mapbox-hosted styles

STEP 01

Install

mapbox-gl comes bundled with the package — no separate install. There is no React Native counterpart.

terminalnpm

npm install @mapconductor/js-sdk-core @mapconductor/js-sdk-react \
            @mapconductor/react-for-mapbox

STEP 02

Import the stylesheet

Import it once from your application entry point. Forget it and the map's layout and controls come out wrong.

main.tsxTypeScript

import '@mapconductor/react-for-mapbox/style.css';

STEP 03

Pass the access token (if needed)

The token goes to the state hook, which sets mapboxgl.accessToken globally. Using only the OSM-based designs? Omit it entirely.

HelloMap.tsxTypeScript · React

const mapState = useMapboxViewState({
  id: 'mapbox-map',
  accessToken: import.meta.env.VITE_MAPBOX_ACCESS_TOKEN,
  mapDesignType: MapboxDesign.Streets,
  cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
});

The key goes to the state hook, not to the view component's props — props tend to end up in test logs and snapshots.

CAUTION

Feed the key from a build-time environment variable (import.meta.env.VITE_* under Vite) and keep it out of source control. It reaches the browser either way, so always restrict it by referrer or domain so exposure is harmless.

VERIFY

What you should see

With OsmBright you can verify the setup without any token at all.

HelloMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { MapboxDesign, MapBoxMapView2D, useMapboxViewState } from '@mapconductor/react-for-mapbox';
import '@mapconductor/react-for-mapbox/style.css';

const TOKYO = createGeoPoint({ latitude: 35.6812, longitude: 139.7671 });

export function HelloMap() {
  // No token needed for the OsmBright design
  const mapState = useMapboxViewState({
    id: 'mapbox-map',
    mapDesignType: MapboxDesign.OsmBright,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

  return (
    <MapBoxMapView2D state={mapState} style={{ height: 480 }}>
      <Marker state={markerState} />
    </MapBoxMapView2D>
  );
}

State object

What useMapboxViewState accepts. Mind the exported view names: MapBoxMapView and MapBoxMapView2D, with a capital B.

signatureTypeScript

useMapboxViewState({
  id?: string;
  accessToken?: string;
  mapDesignType?: MapboxMapDesignType; // default MapboxDesign.Streets
  cameraPosition?: MapCameraPosition;  // default MapCameraPosition.Default
})

Map designs

MapboxDesign splits into styles that need a token and styles that do not.

MapboxDesign

Notes

Streets / Outdoors / Light / Dark

Mapbox-hosted — token required

SatelliteStreets

Mapbox-hosted satellite — token required

OsmBright / OsmBrightEn / OsmBrightJa

The OSM styles shared with MapLibre — no token

MapTilerToner* / MapTilerBasic* / OpenMapTiles

Also shared with MapLibre — no token

Troubleshooting

Only the Mapbox styles fail to render

Styles starting with mapbox:// need a token — check accessToken is being passed.
Confirm it is a public token and has not been revoked.

Zoom levels differ from other providers

MapConductor normalises zoom against Google's scale; Mapbox is converted with an empirical offset of googleZoom ≈ mapboxZoom + 1.0.

The map initialises twice in development

React StrictMode double-invokes effects. Every provider detects this and discards the aborted run, so you do not need to turn StrictMode off.

The architecture matches MapLibre's, so changing mapDesignType re-initialises the map.