Docs / Setup / React / Apple MapKit

Apple MapKit setup

How to use Apple MapKit JS on the Web through MapConductor. Unlike the iOS provider, this one needs a JWT token issued by Apple.

PACKAGE

react-for-mapkit

API KEY

JWT token

CSS

None

REACT

19 or newer

Same provider, other platformsiOS

View demoStore Map · React ↗

Before you start

Node.js 18 or newer, React 19 or newer

An Apple Developer account with a MapKit JS Maps ID and private key

STEP 01

Prepare a MapKit JS token

Create a Maps ID and private key in Apple Developer, then sign a JWT on your server. Tokens expire, so long-lived screens need a refresh path.

CAUTION

Never ship the private key to the browser — sign the JWT on the server.

STEP 02

Install

The package loads MapKit JS from Apple's CDN dynamically — no script tag to write.

terminalnpm

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

STEP 03

Pass the token to the state hook

Pass a static token, or a callback that supplies and refreshes one. When both are given, the callback wins.

MapKitMap.tsxTypeScript · React

const state = useMapKitViewState({
  token: import.meta.env.VITE_MAPKIT_TOKEN ?? '',
  mapDesignType: MapKitMapDesign.Standard,
  cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
});

VERIFY

What you should see

The setup is complete when the MapKit map renders.

MapKitMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { MapKitMapDesign, MapKitMapView, useMapKitViewState } from '@mapconductor/react-for-mapkit';

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

export function MapKitMap() {
  const state = useMapKitViewState({
    token: import.meta.env.VITE_MAPKIT_TOKEN ?? '',
    mapDesignType: MapKitMapDesign.Standard,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

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

Map designs

MapKitMapDesign maps onto MapKit's map types.

MapKitMapDesign

Notes

Standard

The standard street map

Satellite

Satellite imagery

Hybrid

Satellite imagery with roads and labels

MutedStandard

A backdrop for your own data

SatelliteFlyover / HybridFlyover

For regions with Flyover coverage

Troubleshooting

The map does not appear

Check the token is not an empty string.
Check the token has not expired — use authorizationCallback to refresh it on long-lived screens.

It will not build on React 18

This package alone requires React 19 or newer.

Switching providers throws a hook-order error

React will not let the hook call order change. Make one small component per provider that calls its own hook — that is exactly how the sample app's providers/ directory is laid out.

The iOS MapKit provider needs neither a key nor initialisation — the same screen code works on both, with the platform picking its own path.