Docs / Setup / React / MapTiler

MapTiler setup

How to render MapTiler Cloud styles on the Web through MapConductor. It renders with maplibre-gl, and the style resolves to a MapTiler Cloud URL carrying your API key.

PACKAGE

react-for-maptiler

API KEY

Required

CSS

Required

REACT NATIVE

None

Same provider, other platformsAndroid iOS

View demoStore Map · React ↗

Before you start

Node.js 18 or newer

A MapTiler Cloud account and API key

STEP 01

Install

Install the core, the React bindings and the provider package. Swapping providers changes only that third one.

terminalnpm

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

STEP 02

Exclude it from Vite pre-bundling

Under Vite, add the provider to optimizeDeps.exclude. maplibre-gl v6 loads its worker by URL, and pre-bundling does not emit that worker file into .vite/deps, so the request fails.

vite.config.tsTypeScript · Vite

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
    optimizeDeps: {
        exclude: ["@mapconductor/react-for-maptiler", "@mapconductor/js-sdk-core"],
    },
    plugins: [react()],
});

STEP 03

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-maptiler/style.css';

STEP 04

Pass the API key to the state hook

The key is woven into the style JSON URL: https://api.maptiler.com/maps/<style>/style.json?key=…

MapTilerMap.tsxTypeScript · React

const state = useMapTilerViewState({
  apiKey: import.meta.env.VITE_MAPTILER,
  mapDesignType: MapTilerDesign.Streets,
  cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
});

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 map renders in a MapTiler style.

MapTilerMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { MapTilerDesign, MapTilerMapView2D, useMapTilerViewState } from '@mapconductor/react-for-maptiler';
import '@mapconductor/react-for-maptiler/style.css';

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

export function MapTilerMap() {
  const state = useMapTilerViewState({
    apiKey: import.meta.env.VITE_MAPTILER,
    mapDesignType: MapTilerDesign.Streets,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

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

Map designs

MapTilerDesign covers the MapTiler Cloud reference styles.

MapTilerDesign

Notes

Streets / StreetsDark / StreetsLight

The standard road map plus light and dark variants

Basic / Bright

Pared-back styles

Satellite

Satellite imagery

Outdoor / Winter / Topo

Outdoor, winter and topographic

Toner / Dataviz / Backdrop

Backdrops for your own data

Ocean / Landscape / Aquarelle / OpenStreetMap

Further themed styles

Troubleshooting

The map stays blank

Check apiKey is not an empty string — a missing environment variable is the usual cause.
Confirm the key is active in MapTiler Cloud and you are within your quota.

The map's layout or controls look broken

Check you imported style.css.

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.

It uses the same renderer as MapLibre, so its behaviour and constraints match that provider.