Map quickstart

VERSION 0.45.8 PUBLIC PREVIEW

This guide will help you set up your project and visualize your first TomTom map in just a few minutes. You’ll learn the minimal steps needed to install the SDK, configure your API key, and display an interactive map on your webpage.

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

Before getting started, ensure you have the following requirements:

Node.js and npm/pnpm installed for package management (Node.js 22+ recommended)
TomTom API key from the TomTom Developer Portal
Modern browser with WebGL support for optimal map rendering performance

Installing Dependencies

Follow the complete Project setup guide for detailed installation instructions, or use this quick setup:

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

Peer dependencies (installed automatically with above commands):

maplibre-gl (v5) - Map rendering engine
lodash-es (v4) - Utility functions
zod (v4) - Schema validation

MapLibre CSS

The SDK will automatically download the CSS for the MapLibre version you installed.

Otherwise, you can specify the MapLibre CSS in your project if you want to override some maplibre styles with predictable results, or if you need to ensure a different version is used.

If you want to include a specific MapLibre CSS you can do it in two ways:

Import in your JavaScript/TypeScript files (preferred):

1
import 'maplibre-gl/dist/maplibre-gl.css';

Or directly in your HTML file (replace @VERSION with the desired version or omit for latest):

1
<!-- Include in your HTML head -->
2
<link href="https://unpkg.com/maplibre-gl@VERSION/dist/maplibre-gl.css" rel="stylesheet" />

Basic HTML Setup

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

Here’s a complete example that demonstrates all the essential concepts for creating a TomTom map with various configuration options:

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

4
// Configure global SDK settings
5
TomTomConfig.instance.put({
6
    apiKey: 'YOUR_API_KEY_HERE',
7
});
8

9
const map = new TomTomMap({
10
    mapLibre: {
11
        container: 'map'
12
    }
13
});

Next Step

Now that you have a basic map running, learn about TomTom Maps configuration and usage patterns in our comprehensive TomTom Maps Introduction guide.