Docs / Setup / React / TomTom

TomTom setup

How to use TomTom Orbis Maps on the Web through MapConductor, wrapping @tomtom-org/maps-sdk (which is maplibre-based).

PACKAGE

react-for-tomtom

API KEY

Required

CSS

None

REACT NATIVE

None

Same provider, other platformsAndroid iOS

View demoStore Map · React ↗

Before you start

Node.js 18 or newer

A TomTom Orbis Maps API key from the Developer Portal

STEP 01

Install

@tomtom-org/maps-sdk and maplibre-gl both come bundled with the package.

terminalnpm

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

STEP 02

Pass the API key to the state hook

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

TomTomMap.tsxTypeScript · React

const state = useTomTomViewState({
  apiKey: import.meta.env.VITE_TOMTOM_API_KEY,
  mapDesignType: TomTomDesign.Standard,
  cameraPosition: createMapCameraPosition({ position: AMSTERDAM, zoom: 11 }),
});

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

The setup is complete when the TomTom map renders.

TomTomMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { TomTomDesign, TomTomMapView2D, useTomTomViewState } from '@mapconductor/react-for-tomtom';

const AMSTERDAM = createGeoPoint({ latitude: 52.3676, longitude: 4.9041 });

export function TomTomMap() {
  const state = useTomTomViewState({
    apiKey: import.meta.env.VITE_TOMTOM_API_KEY,
    mapDesignType: TomTomDesign.Standard,
    cameraPosition: createMapCameraPosition({ position: AMSTERDAM, zoom: 11 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'ams', position: AMSTERDAM }));

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

Map designs

TomTomDesign covers the Orbis Maps styles, in light/dark pairs.

TomTomDesign

Notes

Standard / StandardLight / StandardDark

The standard browsing style

Driving / DrivingLight / DrivingDark

Tuned for driving

MonoLight / MonoDark

Monochrome — a backdrop for your own data

Satellite

Satellite imagery

Troubleshooting

The map stays blank

Check apiKey is not an empty string.
Confirm the key was issued for Orbis Maps.

Zoom differs from other providers

TomTom's zoom is latitude-dependent; MapConductor converts it to the Google-equivalent scale using the camera latitude.

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.

TomTomMapView is the 3D view and TomTomMapView2D the 2D one; they share a state object.