MapWidgetSdk - Documentation

This SDK provides a simplified wrapper, allowing easy initialization and manipulation of interactive maps, markers, and heatmaps within frontend applications.

📦 Installation

Install the SDK

npm install map-widget-sdk

<link
  href="https://api.mapbox.com/mapbox-gl-js/v3.14.0/mapbox-gl.css"
  rel="stylesheet"
/>

🚀 Usage Example (React)

import MapWidgetSdk from "map-widget-sdk";
import heatmapGeoJSON from "./heatmap.json";

useEffect(() => {
  const map = MapWidgetSdk.initMap("map", {
    accessToken: "your_mapbox_token",
    center: [74.2683, 31.447],
    zoom: 15,
    style: "streetsView",
  });

  map.on("load", () => {
    map.resize();
    MapWidgetSdk.initResponsiveMap(map);
    MapWidgetSdk.addSingleMarker(map, 31.44705, 74.26842, "My Location");
    MapWidgetSdk.initHeatMapLayer(map, heatmapGeoJSON);
    MapWidgetSdk.flyToMarkerLocation(map, 74.2398, 31.4428, 15);
  });

  return () => map.remove();
}, []);

<div id="map" style={{ width: "400px", height: "300px" }}></div>;

🧩 Available Methods

1. initMap(containerId, options)

Initializes a map inside a target HTML element.

Parameters:

• containerId (string): ID of the DOM element (e.g., 'map')

• options (object):

  • accessToken (required): Your Mapbox access token
  • center (array): [lng, lat] coordinates (default: [0, 0])
  • zoom (number): Zoom level (default: 5)
  • style (string): Map style (streetsView, satelliteView) or full custom style URL

Returns:

• A Map instance

2. addSingleMarker(map, lat, lng, label)

Adds a marker to the given map with an optional popup label.

Parameters:

• map: map instance
• lat (number): Latitude
• lng (number): Longitude
• label (string): HTML label for the popup (optional)

Returns:

• The marker instance

3. removeMarker(marker)

Removes a given marker from the map.

Parameters:

• marker: A Marker instance

4. addMarkersFromGeoJSON(map, geoJSON)

Adds multiple markers from a valid GeoJSON FeatureCollection.

Example:

const geoJSON = {
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      properties: { lat: 31.44698, lng: 74.2683, label: "Marker 1" },
      geometry: { type: "Point", coordinates: [74.2683, 31.44698] },
    },
    ...
  ]
};
MapWidgetSdk.addMarkersFromGeoJSON(map, geoJSON);

5. flyToMarkerLocation(map, lng, lat, zoom = 14)

Smoothly pans and zooms the map to the specified location.

Parameters:

• map: map instance
• lng (number): Longitude
• lat (number): Latitude
• zoom (number): Zoom level (default: 14)

6. initHeatMapLayer(map, geoJSON)

Adds a heatmap layer from a GeoJSON dataset with Point features.

Parameters:

• map: map instance
• geoJSON: GeoJSON FeatureCollection with Point geometries

Notes:

• Use for high-density data visualization
• Default paint config uses heatmap-intensity, color, and radius

7. initResponsiveMap(map)

Automatically resizes the map on window resize.

Parameters:

• map: map instance

🌐 Supported Map Styles

Use one of the following aliases (or pass a custom Mapbox Studio style URL):

| Alias | Mapbox Style URL | | --------------- | ------------------------------------- | | streetsView | mapbox://styles/mapbox/streets-v11 | | satelliteView | mapbox://styles/mapbox/satellite-v9 |

🔚 Cleanup

Always remove the map on unmount to avoid memory leaks:

useEffect(() => {
  const map = MapWidgetSdk.initMap(...);

  return () => map.remove();
}, []);

🧠 Tip: Switching Styles

You can dynamically toggle between styles:

<button onClick={() => setMapView(!mapView)}>Change View</button>;
style: mapView ? "streetsView" : "satelliteView";