gistda-sphere-react

Quick start

Render your first map with gistda-sphere-react

Minimal example

Wrap your app with SphereProvider, then use SphereMap to render a map:

import { SphereProvider, SphereMap, Marker } from 'gistda-sphere-react';

function App() {
  return (
    <SphereProvider apiKey="YOUR_API_KEY">
      <SphereMap
        center={{ lon: 100.5018, lat: 13.7563 }}
        zoom={10}
        style={{ width: '100%', height: '500px' }}
      >
        <Marker
          position={{ lon: 100.5018, lat: 13.7563 }}
          title="Bangkok"
          detail="Capital of Thailand"
        />
      </SphereMap>
    </SphereProvider>
  );
}

Using the Next.js App Router? This example works as it is in a Server Component, such as app/page.tsx. Code that uses hooks or event handlers like onClick goes in a Client Component: add "use client"; at the top of its file.

Key concepts

  1. SphereProvider loads the Sphere script. Put it above everything that uses the map.
  2. SphereMap is the map. Give it (or its container) a height, or it collapses to 0 px.
  3. Components such as Marker, Polygon, Layer and Tag go inside SphereMap. They appear when they mount and disappear when they unmount, so the map follows your state.
  4. Hooks such as useMapControls, useSearch, useRoute and useUi work anywhere under SphereProvider, for example in a sidebar.
  5. Web services such as routing, geocoding and agriculture data are available through useSphereServices, even without a map.
  6. Language: maps, search results and route directions are in Thai unless you set language="en" on SphereProvider.

Adding overlays

Place overlay components as children of SphereMap:

import { Circle, Marker, Polygon, SphereMap } from "gistda-sphere-react";

<SphereMap style={{ width: '100%', height: '500px' }}>
  <Marker position={{ lon: 100.5018, lat: 13.7563 }} title="Bangkok" />
  <Polygon
    positions={[
      { lon: 100.41, lat: 13.78 },
      { lon: 100.47, lat: 13.78 },
      { lon: 100.44, lat: 13.73 },
    ]}
    fillColor="rgba(255, 0, 0, 0.3)"
    lineColor="red"
  />
  <Circle
    center={{ lon: 100.58, lat: 13.75 }}
    radius={0.03}
    fillColor="rgba(0, 100, 255, 0.3)"
    lineColor="blue"
  />
</SphereMap>

Next steps

On this page