Map quickstart

Install the SDK, set your API key and show an interactive TomTom map, like the one below. Creating your first map has the whole app.

Prerequisites and setup

1. Node.js 22+ and npm, pnpm or Yarn
2. A TomTom API key from my.tomtom.com
3. 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

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

# pnpm - enable auto-install-peers for easiest setup
echo "auto-install-peers=true" >> .npmrc
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:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>TomTom Map Application</title>
    <style>
        #map { width: 100%; height: 400px; }
    </style>
</head>
<body>
    <div id="map"></div>
    <script type="module" src="./index.ts"></script>
</body>
</html>

Creating your first map

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

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

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

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.