gistda-sphere-react

useMapControls

Move, zoom, rotate and tilt the map, and manage layers, filters and language from anywhere

useMapControls controls the map imperatively, for example from buttons in a sidebar. It works anywhere under SphereProvider, and the same methods are on SphereMap's ref.

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

function Toolbar() {
  const { goTo, zoomIn, zoomOut, setRotate, setPitch } = useMapControls();
  return (
    <>
      <button onClick={() => goTo({ center: { lon: 98.9853, lat: 18.7883 }, zoom: 12 })}>Chiang Mai</button>
      <button onClick={() => zoomIn()}>+</button>
      <button onClick={() => zoomOut()}>−</button>
      <button onClick={() => { setRotate(0); setPitch(0); }}>Reset view</button>
    </>
  );
}

Camera

MethodDescription
goTo(options, animate?)Move to a view. options: center, zoom, rotate (or bearing), pitch, padding, duration. Animates by default.
getView()Center, zoom, rotation, tilt and visible box in one object, or null before the map is ready.
setCenter(location, animate?) / getCenter()Center of the map.
setZoom(zoom, animate?) / getZoom()Zoom level.
zoomIn(animate?) / zoomOut(animate?)Zoom one level in or out.
setRotate(angle, animate?) / getRotate()Rotation in degrees, clockwise from north.
setPitch(angle) / getPitch()Tilt in degrees.
setBound(bound, options?) / getBound()Fit the map to a { minLon, minLat, maxLon, maxLat } box (with padding, maxZoom…), or read the visible box.
panBy({ x, y }, animate?)Pan by pixels.
setZoomRange(range) / getZoomRange()Zoom levels users can reach.

rotate and bearing are the same angle: rotate matches SphereMap's prop and setRotate, and bearing is MapLibre's name for it. If you pass both, bearing wins.

Layers and appearance

MethodDescription
setBaseLayer(layer)Change the base map: a built-in name, a sphere.Layer, or a MapLibre style URL or object.
addLayer(layer, beforeId?) / removeLayer(layer)Add or remove a layer on top of the base map.
clearLayers() / getLayers()Remove all added layers / list the map's layers.
setFilter(filter) / getFilter()Color filter: "Dark", "Light", "Protanopia" or "Deuteranopia". "None" or false clears it.
setLanguage(language) / getLanguage()Labels and UI language, "th" or "en".
loadPredefinedOverlay(type, options?) / unloadPredefinedOverlay(type)Live "cameras", "events" or "aqi" overlays.

Other

MethodDescription
isReadytrue once the map is ready. Methods do nothing before that.
resize()Re-measure the map after its container changes size.
repaint()Redraw the map.

For state that should follow your app (language, filter, base map, zoom limits, controls), the SphereMap props are simpler. Use these methods for actions, such as flying to a place when a list item is clicked.

On this page