Map quickstart

VERSION 1.0.0-rc.3 PUBLIC PREVIEW

Install the SDK, set your API key and show an interactive TomTom map. The code below is the whole app. Change the center or zoom and the map follows.

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
import './style.css';
import { API_KEY } from './config';

// (Set your own API key when working in your own environment)
TomTomConfig.instance.put({ apiKey: API_KEY, language: 'en-GB' });

new TomTomMap({
    mapLibre: {
        container: 'sdk-map',
        center: [4.8156, 52.4414],
        zoom: 8,
    },
});

Open Sandbox

Prerequisites and setup

Node.js 22+ and npm, pnpm or Yarn
A TomTom API key from my.tomtom.com
A browser with WebGL, which MapLibre renders with

Before you ship, decide where this key will live. Anyone who opens the page can read a key used from the browser. A key used from Node.js cannot. See Where your API key runs for which case you are in and what to do, and TomTom’s API key management best practices for key restrictions, rotation and monitoring.

Installing dependencies

1
# npm or Yarn - automatic peer dependency installation
2
npm install @tomtom-org/maps-sdk
3

4
# pnpm - enable auto-install-peers for easiest setup
5
echo "auto-install-peers=true" >> .npmrc
6
pnpm install @tomtom-org/maps-sdk

maplibre-gl and the SDK’s other peer dependencies install with it. The Project setup guide lists which peer dependencies each bundle needs and how to install them by hand.

Basic HTML setup

Give the map container a height. Otherwise, it renders with none:

1
<!DOCTYPE html>
2
<html lang="en">
3
<head>
4
    <meta charset="UTF-8">
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
    <title>TomTom Map Application</title>
7
    <style>
8
        #map { width: 100%; height: 400px; }
9
    </style>
10
</head>
11
<body>
12
    <div id="map"></div>
13
    <script type="module" src="./index.ts"></script>
14
</body>
15
</html>

Creating your first map

1
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
2
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
3

4
TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });
5

6
const map = new TomTomMap({
7
    mapLibre: {
8
        container: 'map'
9
    }
10
});

The map opens in the default streetLight style. The SDK applies the MapLibre CSS itself, so you don’t import a stylesheet (MapLibre CSS).

Next step

The map introduction explains how TomTomMap and its modules fit together. The TomTomMap guide covers every map option.