Advanced

Access the underlying AMap JS API instance for advanced customization.

Access the underlying AMap JS API map instance to use any feature from the AMap JS API JS API. You can use either a ref or the useMap hook.

Tip: Check the AMap JS API JS documentation for the full list of available methods and events.

Using a Ref

The simplest way to access the map instance. Use a ref to call map methods from event handlers or effects.

import { Map, type MapRef } from "@/components/ui/map";
import { useRef } from "react";

function MyMapComponent() {
  const mapRef = useRef<MapRef>(null);

  const handleFlyTo = () => {
    // Access the AMap JS API map instance via ref
    mapRef.current?.flyTo({ center: [-74, 40.7], zoom: 12 });
  };

  return (
    <>
      <button onClick={handleFlyTo}>Fly to NYC</button>
      <Map ref={mapRef} center={[-74, 40.7]} zoom={10} />
    </>
  );
}

Using the Hook

For child components rendered inside Map, use the useMap hook to access the map instance and listen to events.

import { Map, useMap } from "@/components/ui/map";
import { useEffect } from "react";

// For child components inside Map, use the useMap hook
function MapEventListener() {
  const { map, isLoaded } = useMap();

  useEffect(() => {
    if (!map || !isLoaded) return;
    
    const handleClick = (e) => {
      console.log("Clicked at:", e.lngLat);
    };

    map.on("click", handleClick);
    return () => map.off("click", handleClick);
  }, [map, isLoaded]);

  return null;
}

// Usage
<Map center={[-74, 40.7]} zoom={10}>
  <MapEventListener />
</Map>

useMapEvent

useMapEvent(event, handler) is a convenience hook that subscribes to any AMap map event and automatically unsubscribes on unmount. It eliminates the boilerplate of writing useMap + useEffect + map.on/off yourself. The hook must be called from a component rendered inside Map.

useMapBounds

useMapBounds() returns the current viewport bounding box as { north, south, east, west } (or null before the map loads). The value updates on every pan and zoom. Useful for fetching data within the visible area.

Example: Custom Controls

This example shows how to create custom controls that manipulate the map's pitch and bearing, and listen to map events to display real-time values.

Example: Custom GeoJSON Layer

Add custom GeoJSON data as layers with fill and outline styles. This example shows NYC parks with hover interactions.

Example: Markers via Layers

When displaying hundreds or thousands of markers, use GeoJSON layers instead of DOM-based MapMarker components. This approach renders markers on the WebGL canvas, providing significantly better performance.

Extend to Build

You can extend this to build custom features like:

  • Real-time tracking - Live location updates for delivery, rides, or fleet management
  • Geofencing - Trigger actions when users enter or leave specific areas
  • Heatmaps - Visualize density data like population, crime, or activity hotspots
  • Drawing tools - Let users draw polygons, lines, or place markers for custom areas
  • 3D buildings - Extrude building footprints for urban visualization
  • Animations - Animate markers along routes or create fly-through experiences
  • Custom data layers - Overlay weather, traffic, or satellite imagery
PreviousLayers