MapConductorGoogle Maps setup
How to use Google Maps on the Web through MapConductor. The Google Maps JavaScript API is loaded dynamically, so there is no script tag to write — but 2D and 3D are separate view components.
Before you start
Get an API key
- Enable the Maps JavaScript API in the Google Cloud Console.
- Create an API key under Credentials.
- Restrict the key by HTTP referrer to the domains you serve from.
Install
The Google Maps JavaScript API is loaded dynamically via @googlemaps/js-api-loader, which ships bundled with the package. Nothing else to install, and no CSS to import.
npm install @mapconductor/js-sdk-core @mapconductor/js-sdk-react \
@mapconductor/react-for-googlemapsPass the key to the state hook
The key goes to the state hook, not to the view component's props — props tend to end up in test logs and snapshots.
const mapState = useGoogleMapViewState({
id: 'web-google-map',
apiKey: import.meta.env.VITE_GOOGLE_MAPS_API_KEY,
mapDesignType: GoogleMapDesign.Normal,
cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
});Choose between 2D and 3D
Google Maps has two independent stacks, and MapConductor exposes one view for each; they share a state object. Setting mapId also switches the 2D provider's markers to AdvancedMarkerElement — without one it falls back to the legacy renderer.
// Classic 2D map (google.maps.Map)
<GoogleMapView2D state={mapState} mapId="YOUR_MAP_ID" />
// True 3D camera (google.maps.maps3d.Map3DElement)
<GoogleMapView state={mapState} mapId="YOUR_MAP_ID" version="alpha" />VERIFY
What you should see
A map centred on Tokyo with a single marker means you are done.
import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { GoogleMapDesign, GoogleMapView2D, useGoogleMapViewState } from '@mapconductor/react-for-googlemaps';
const TOKYO = createGeoPoint({ latitude: 35.6812, longitude: 139.7671 });
export function HelloMap() {
const mapState = useGoogleMapViewState({
id: 'web-google-map',
apiKey: import.meta.env.VITE_GOOGLE_MAPS_API_KEY,
mapDesignType: GoogleMapDesign.Normal,
cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
});
const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));
return (
<GoogleMapView2D state={mapState} style={{ height: 480 }}>
<Marker state={markerState} />
</GoogleMapView2D>
);
}State object
What useGoogleMapViewState accepts.
useGoogleMapViewState({
id?: string;
apiKey?: string; // required in practice
mapId?: string; // Advanced Markers / cloud styling
mapDesignType?: GoogleMapDesignType; // default GoogleMapDesign.Normal
cameraPosition?: MapCameraPosition; // default MapCameraPosition.Default
})Map designs
GoogleMapDesign mirrors Google's map type ids.
Troubleshooting
The map does not appear
- Check the key reaches the state hook and that the environment variable resolved.
- Verify the key's referrer restriction matches the domain you serve from.
The 3D view throws
- Check you are not passing Terrain or None — the 3D view accepts only Normal, Hybrid and Satellite.
- Confirm you passed version="alpha".
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.
Next
The 3D view rescales the camera range on viewport changes, so zoom looks consistent across window sizes.