Ref APIs
Imperative methods on the map and on every overlay, through React refs
Every component that draws something accepts a ref, which gives you its imperative methods and the underlying Sphere object.
import { useRef } from "react";
import { Polygon, SphereMap, type PolygonRef, type SphereMapRef } from "gistda-sphere-react";
function Example() {
const mapRef = useRef<SphereMapRef>(null);
const zoneRef = useRef<PolygonRef>(null);
const zoomToZone = () => {
const bound = zoneRef.current?.getBound();
if (bound) mapRef.current?.setBound(bound, { padding: 40 });
};
return (
<SphereMap ref={mapRef}>
<Polygon ref={zoneRef} positions={zone} onClick={zoomToZone} />
</SphereMap>
);
}Ref types
| Component | Ref type | Highlights |
|---|---|---|
SphereMap | SphereMapRef | Camera, layers, filters, language, getMap(). |
Marker | MarkerRef | setPosition, setRotation, togglePopup, getElement. |
Popup | PopupRef | setPosition, setTitle, setDetail. |
Polygon | PolygonRef | getArea, union, intersection, difference, split. |
Polyline | PolylineRef | getLength, union. |
Circle | CircleRef | getArea, getRadius, getCenter. |
Rectangle | RectangleRef | Same as polygons. |
Dot | DotRef | getPosition, setPosition. |
GeoJson | GeoJsonRef | getOverlays(), getBound(). |
ObjectOverlay | ObjectOverlayRef | getObject(), getOverlays(). |
MenuBar | MenuBarRef | getMenuBar(), select(index). |
Shared shape methods
Markers, dots and the shapes share these spatial methods (OverlaySpatialMethods):
| Method | Description |
|---|---|
contains(target) | Whether a location or overlay is inside this one. |
intersects(target) | Whether they touch or overlap. |
within(overlay) | Whether this one is inside another overlay. |
distanceTo(target, language?) | Shortest distance in meters, or text with a language. |
shift({ lon, lat }) | Move by an offset in degrees. |
toGeoJSON() | The overlay as a GeoJSON feature. |
Shapes also have getBound, getCentroid, getPivot, rotate, updateStyle and togglePopup (GeometryRefMethods). See Spatial analysis for examples.
Ref methods are safe to call at any time. They return null or false while the overlay doesn't exist yet. Call them from event handlers or effects, not during render.