gistda-sphere-react

SphereProvider

Loads the Sphere API and shares it with every map, hook and component below it

SphereProvider loads the GISTDA Sphere script once per page and makes it available to everything inside it. Put it near the root of your app, above every SphereMap and every component that uses the hooks.

"use client";

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

export function App() {
  return (
    <SphereProvider apiKey={process.env.NEXT_PUBLIC_SPHERE_API_KEY!}>
      <SphereMap style={{ height: 400 }} />
    </SphereProvider>
  );
}

Props

PropTypeDefaultDescription
apiKeystringrequiredYour Sphere API key. See API key.
childrenReactNoderequiredYour app.
language"th" | "en"–Default language of every map below it, of useSphereServices and of useTagCategories labels. Maps without their own language use it. Without either, maps show Thai. See Language.
onLoad() => void–Called once the Sphere script has loaded.
onError(error: Error) => void–Called when the script can't load, for example when the key isn't allowed on this domain.
scriptUrlstringhttps://api.sphere.gistda.or.th/map/?key=…Load the script from another URL, such as a proxy.
formatPoi(poi: PoiResult, language: string) => HTMLElement–Build the content of the popups Sphere shows for POI tags and search results.
poiPopupOptions(source, id, name, language) => PopupOptions–Replace those POI popups entirely. Takes priority over formatPoi.

Loading state

The script loads asynchronously. Hooks report isReady, and useSphere() gives you the loading state directly:

import { useSphere } from "gistda-sphere-react";

function Status() {
  const { isLoaded, error } = useSphere();
  if (error) return <p>Couldn't load the map: {error.message}</p>;
  return isLoaded ? null : <p>Loading map…</p>;
}

Language

Maps show Thai labels by default. Set language once on the provider to switch every map, along with search results, route instructions and web services results:

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

<SphereProvider apiKey={apiKey} language="en">
  <SphereMap style={{ height: 400 }} />
</SphereProvider>

A map's own language prop takes priority over the provider's.

Customizing POI popups

When users click a POI from <Tag> or a search result, Sphere shows a popup with the place's details. Use formatPoi to render your own content:

import { SphereProvider } from "gistda-sphere-react";

<SphereProvider
  apiKey={apiKey}
  formatPoi={(poi) => {
    const element = document.createElement("div");
    const name = document.createElement("strong");
    name.textContent = poi.name;
    const address = document.createElement("p");
    address.textContent = poi.address ?? "";
    element.append(name, address);
    return element;
  }}
>

Insert place data with textContent, as above. If you build HTML with innerHTML instead, escape every value first.

To take over the popup completely, for example to load details from your own service, return popup options from poiPopupOptions:

import { SphereProvider } from "gistda-sphere-react";

<SphereProvider
  apiKey={apiKey}
  poiPopupOptions={(source, id, name) => ({
    title: name,
    loadDetail: async (element) => {
      const details = await fetch(`/api/places/${id}`).then((r) => r.json());
      element.textContent = details.summary;
    },
  })}
>

Both callbacks are installed on sphere.Util while the provider is mounted and restored when it unmounts.

Using it with Next.js

Every component in this library is a Client Component, so you can render SphereProvider and SphereMap from Server Components too, such as your root layout:

app/layout.tsx
import { SphereProvider } from "gistda-sphere-react";
import type { ReactNode } from "react";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SphereProvider
          apiKey={process.env.NEXT_PUBLIC_SPHERE_API_KEY!}
          language="en"
        >
          {children}
        </SphereProvider>
      </body>
    </html>
  );
}

Server Components can't pass functions as props or call hooks. Put event handlers such as onClick, callbacks such as formatPoi, and hooks in a Client Component (a file starting with "use client"). The web services client works on the server too.

One map or several

One provider can hold any number of maps. Components and hooks used inside a SphereMap always work with that map. Hooks used outside a map, such as in a sidebar, work with the provider's current map, which is the one that became ready most recently. If you need sidebar hooks for several maps at once, give each map its own SphereProvider.

On this page