gistda-sphere-react

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

PropTypeDefaultDescription
positionLocation | GeoJSON pointrequiredWhere the marker is. Changing it moves the marker without re-creating it.
titlestring–Tooltip on hover, and the popup title.
detailstring–Popup text shown on click.
popupPopupOptions–Full popup configuration (overrides detail).
popupContentReactNode–React content rendered in the popup.
childrenReactNode–React content used as the icon.
iconIconSphere's pinImage (url, urlHD) or HTML (html) icon, with size and offset.
rotatenumber0Live. Clockwise rotation in degrees.
draggablebooleanfalseLive. Let users drag the marker.
animateboolean | number–Slide to new positions: true (150 ms) or a duration in ms. HTML/React icons only.
clickableboolean–Show a pointer cursor on hover.
visibleRangeRangeall levelsOnly show the marker between these zoom levels.
zIndexnumber–Stacking order.
optionsRecord<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.
refRef<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);
MethodDescription
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.

On this page