Docs / Setup / React / Azure Maps

Azure Maps setup

How to use Azure Maps on the Web through MapConductor, authenticated with an Azure subscription key.

PACKAGE

react-for-azuremaps

API KEY

Subscription key

CSS

Required

REACT NATIVE

None

View demoStore Map · React ↗

Before you start

Node.js 18 or newer

An Azure Maps account and subscription key

STEP 01

Install

azure-maps-control comes bundled with the package.

terminalnpm

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

STEP 02

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

STEP 03

Pass the subscription key

The key goes to the state hook's subscriptionKey. Leave it empty and the map never initialises.

AzureMap.tsxTypeScript · React

const state = useAzureMapsViewState({
  subscriptionKey: import.meta.env.VITE_AZURE_MAPS_SUBSCRIPTION_KEY ?? '',
  mapDesignType: AzureMapsDesign.Road,
  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 Azure Maps map renders.

AzureMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { AzureMapsDesign, AzureMapsMapView, useAzureMapsViewState } from '@mapconductor/react-for-azuremaps';
import '@mapconductor/react-for-azuremaps/style.css';

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

export function AzureMap() {
  const state = useAzureMapsViewState({
    subscriptionKey: import.meta.env.VITE_AZURE_MAPS_SUBSCRIPTION_KEY ?? '',
    mapDesignType: AzureMapsDesign.Road,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

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

Map designs

AzureMapsDesign maps onto the Azure Maps styles.

AzureMapsDesign

Notes

Road / RoadShadedRelief

The road map, plain and with shaded relief

Satellite / SatelliteRoadLabels

Satellite imagery, with or without road labels

GrayscaleLight / GrayscaleDark

Backdrops for your own data

Night

The night style

HighContrastLight / HighContrastDark

High-contrast styles

Blank / BlankAccessible

No basemap

Troubleshooting

The map does not appear

Check subscriptionKey is not an empty string.
Confirm the key is active in the Azure portal.

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.

The subscription key reaches the browser. In production, restrict its scope or move to one of Azure's other authentication modes.