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
| Method | Description |
|---|---|
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
| Method | Description |
|---|---|
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
| Method | Description |
|---|---|
isReady | true 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.