gistda-sphere-react

useMap

Get the raw Sphere map, the MapLibre map behind it, and the sphere namespace

useMap gives you direct access to the Sphere API for anything this library doesn't wrap. It works anywhere under SphereProvider.

import { useMap } from "gistda-sphere-react";

function ZoomLabel() {
  const { map, isReady } = useMap();
  if (!isReady || !map) return null;
  return <span>Zoom: {map.zoom()}</span>;
}

Return value

PropertyTypeDescription
mapSphereMapInstance | nullThe sphere.Map instance.
sphereSphereNamespace | nullThe global sphere namespace (classes, enums, Util).
isReadybooleantrue once the map is ready.

The MapLibre map

Sphere draws with MapLibre GL JS. map.Renderer is the MapLibre map, so MapLibre features and plugins work too:

import { useMap } from "gistda-sphere-react";
import { useEffect } from "react";

const { map } = useMap();

useEffect(() => {
  const renderer = map?.Renderer;
  if (!renderer) return;
  const onMove = () => console.log(renderer.getBearing());
  renderer.on("move", onMove);
  return () => {
    renderer.off("move", onMove);
  };
}, [map]);

See Using MapLibre plugins for a complete example.

Inside a map

Within a SphereMap, useMapContext() returns { map, isReady } for that specific map. That matters when one provider holds several maps.

Prefer the typed components and hooks where they exist: they clean up after themselves on unmount, which raw calls don't.

On this page