API Reference

All parts of the component that you can use and combine to build your map.

<Map>
  <MapMarker longitude={...} latitude={...}>
    <MarkerContent>
      <MarkerLabel />
    </MarkerContent>
    <MarkerPopup />
    <MarkerTooltip />
  </MapMarker>

  <MapPopup longitude={...} latitude={...} />
  <MapControls />
  <MapRoute coordinates={...} />
  <MapClusterLayer data={...} />
  <MapPolygon coordinates={...} />
  <MapCircle center={...} radius={...} />
  <MapHeatmap data={...} />
  <MapTrafficLayer />
  <MapSatelliteLayer />
</Map>

The root container component that initializes AMap JS API and provides context to child components. Automatically handles theme switching between light and dark modes.

A hook that provides access to the AMap map instance and loading state. Must be used within a Map component.

const { map, isLoaded } = useMap();

Returns map (AMap.Map) and isLoaded (boolean) tells you if the map is loaded and ready to use.

Subscribes to a map event and cleans up automatically on unmount. Must be called inside a Map component.

useMapEvent("click", (e) => console.log(e.lnglat));

Accepts any AMap map event name such as click, moveend, zoomend, pitchchange, etc.

Returns the current viewport bounds, updating automatically on every pan/zoom. Must be called inside a Map component.

const bounds = useMapBounds();
// { north, south, east, west } | null

AMap uses the GCJ-02 coordinate system (China national standard). GPS devices output WGS-84. Use these utilities to convert between them.

import { wgs84ToGcj02, gcj02ToWgs84 } from "amapcn";

// Convert GPS coordinates to AMap (GCJ-02)
const [lng, lat] = wgs84ToGcj02(121.473, 31.230);

// Convert back to WGS-84
const [wgsLng, wgsLat] = gcj02ToWgs84(lng, lat);

Renders map control buttons (zoom, compass, locate, fullscreen, scale). Must be used inside Map.

A container for marker-related components. Provides context for its children and handles marker positioning.

Extends MarkerOptions from AMap JS API (excluding element).

Renders the visual content of a marker. Must be used inside MapMarker. If no children provided, renders a default blue dot marker.

Renders a popup attached to the marker that opens on click. Must be used inside MapMarker.

Extends PopupOptions from AMap JS API (excluding className and closeButton).

Renders a tooltip that appears on hover. Must be used inside MapMarker.

Extends PopupOptions from AMap JS API (excluding className, closeButton, and closeOnClick as tooltips auto-dismiss on hover out).

Renders a text label above or below the marker. Must be used inside MarkerContent.

A standalone popup component that can be placed anywhere on the map without a marker. Must be used inside Map.

Extends PopupOptions from AMap JS API (excluding className and closeButton).

Renders a line/route on the map connecting coordinate points. Must be used inside Map.

Renders clustered point data using AMap JS API's native clustering. Automatically groups nearby points into clusters that expand on click. Must be used inside Map. Supports a generic type parameter for typed feature properties: MapClusterLayer<MyProperties>.

Draws a filled polygon. Must be used inside Map. Requires at least 3 coordinate pairs. See Shapes for a full example.

Draws a circle with a given center and radius in meters. Must be used inside Map. See Shapes for a full example.

Renders a density heatmap. Must be used inside Map. Uses AMap's AMap.HeatMap plugin. See Heatmap for a full example.

Overlays real-time traffic conditions. Must be used inside Map. See Layers for a full example.

Overlays satellite/aerial imagery. Must be used inside Map. See Layers for a full example.