Marker
A point on the map, with an image, HTML or React icon and an optional popup
import { Marker, SphereMap } from "gistda-sphere-react";
<SphereMap center={{ lon: 100.5018, lat: 13.7563 }} style={{ height: 400 }} zoom={12}>
<Marker
position={{ lon: 100.5018, lat: 13.7563 }}
title="Bangkok"
detail="Capital of Thailand"
draggable
onDrop={(marker, position) => console.log("Moved to", position)}
/>
</SphereMap>The shorter samples below leave out <SphereMap>, but every overlay goes inside one.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
position | Location | GeoJSON point | required | Where the marker is. Changing it moves the marker without re-creating it. |
title | string | – | Tooltip on hover, and the popup title. |
detail | string | – | Popup text shown on click. |
popup | PopupOptions | – | Full popup configuration (overrides detail). |
popupContent | ReactNode | – | React content rendered in the popup. |
children | ReactNode | – | React content used as the icon. |
icon | Icon | Sphere's pin | Image (url, urlHD) or HTML (html) icon, with size and offset. |
rotate | number | 0 | Live. Clockwise rotation in degrees. |
draggable | boolean | false | Live. Let users drag the marker. |
animate | boolean | number | – | Slide to new positions: true (150 ms) or a duration in ms. HTML/React icons only. |
clickable | boolean | – | Show a pointer cursor on hover. |
visibleRange | Range | all levels | Only show the marker between these zoom levels. |
zIndex | number | – | Stacking order. |
options | Record<string, unknown> | – | Extra options for new sphere.Marker(). HTML/React icons also accept MapLibre marker options such as anchor. |
onClick | (marker, location) => void | – | The marker was clicked. |
onDrag | (marker) => void | – | The marker is being dragged. |
onDrop | (marker, location) => void | – | The marker was dropped at location. |
onHover / onLeave | (marker) => void | – | The pointer entered / left the marker. |
ref | Ref<MarkerRef> | – | See Ref. |
React icons
Pass any React content as children to use it as the icon. It renders with your app's styles, state and event handlers:
import { Marker, SphereMap } from "gistda-sphere-react";
<SphereMap center={{ lon: 100.5018, lat: 13.7563 }} style={{ height: 300 }} zoom={11}>
<Marker position={{ lon: 100.5018, lat: 13.7563 }} title="Bangkok">
<span
style={{
background: "#2563eb",
borderRadius: 999,
color: "white",
display: "inline-block",
fontSize: 12,
fontWeight: 600,
padding: "2px 8px",
whiteSpace: "nowrap",
}}
>
Bangkok
</span>
</Marker>
</SphereMap>The icon is centered on the position. To anchor it at its bottom edge, like a pin, pass options={{ anchor: "bottom" }}.
React popups
popupContent renders React into the popup that opens on click:
import { Marker } from "gistda-sphere-react";
<Marker
position={cafe.location}
title={cafe.name}
popupContent={
<div>
<p>{cafe.address}</p>
<button onClick={() => addToFavorites(cafe.id)}>Save</button>
</div>
}
/>Image and HTML icons
import { Marker } from "gistda-sphere-react";
<Marker
position={{ lon: 100.5, lat: 13.75 }}
icon={{
url: "/pin.png",
urlHD: "/pin@2x.png",
size: { width: 32, height: 32 },
offset: { x: 16, y: 32 },
}}
/>
<Marker
position={{ lon: 100.5, lat: 13.75 }}
icon={{ html: '<div class="dot"></div>', offset: { x: 8, y: 8 } }}
/>Moving markers
Update position to move a marker. With animate, HTML and React icons slide to the new spot, which suits live positions such as vehicles:
import { Marker } from "gistda-sphere-react";
<Marker position={bus.location} rotate={bus.heading} animate={1000}>
<BusIcon />
</Marker>Ref
import { Marker, type MarkerRef } from "gistda-sphere-react";
import { useRef } from "react";
const markerRef = useRef<MarkerRef>(null);
<Marker ref={markerRef} position={start} draggable />
markerRef.current?.setPosition({ lon: 100.6, lat: 13.8 }, true);
markerRef.current?.togglePopup(true);| Method | Description |
|---|---|
getMarker() | The underlying sphere.Marker. |
getElement() | The marker's DOM element (HTML and React icons only). |
getPosition() | Current position. |
setPosition(location, animate?) | Move the marker. |
setRotation(angle) | Rotate the icon. |
togglePopup(show?) | Show, hide or toggle the popup. |
contains(target), intersects(target), within(overlay), distanceTo(target, language?) | Spatial tests. See Spatial analysis. |
toGeoJSON() | The marker as a GeoJSON feature. |
shift({ lon, lat }) | Move by an offset in degrees. |
Ref or position?
position places the marker when it's created, and moves it each time the prop changes to a new location. setPosition and dragging move the marker without changing the prop, so it stays there until position changes. Changing icon, title, detail or the popup re-creates the marker at position, so to keep a moved marker in place, save its new location in state, for example from onDrop:
import { type Location, Marker } from "gistda-sphere-react";
import { useState } from "react";
const [position, setPosition] = useState<Location>({ lon: 100.5018, lat: 13.7563 });
<Marker draggable onDrop={(_, location) => setPosition(location)} position={position} />To manage many markers as a list, see useMarkers.