Upgrading
What changed in each release, what to update in your code, and what's new
Upgrading to 2.1
2.1 makes the library easier to use with Next.js and on servers, adds features developers asked for, and fixes bugs. Most apps upgrade without changes, but check the list below if you style the map's container, use the raw map's types, or call useMapZoom or useMapLocation.
Changes in 2.1
- The map draws into an inner element.
SphereMapnow gives Sphere a childdivthat fills its container, so maps remounted by React StrictMode, client-side navigation, tabs or modals render in place. If your CSS or code reads MapLibre's classes (such as.maplibregl-map) on the element you passclassNameorstyleto, use its first child instead. A container with no CSS position getsposition: relative. - Map getters return values. In the raw map types, getters such as
map.zoom()andmap.location()are typed as their value (number,Location) instead ofnumber | SphereMap. Remove casts you added for them. - Search key errors. The web services client now reports the search service's API key error with code
"key"instead of"parse". useMapZoomanduseMapLocationpass the new zoom level or center to the handler. Handlers without arguments keep working.
Fixed in 2.1
- Maps that mount after the Sphere script has loaded no longer draw in the page's top-left corner under React StrictMode (development builds of Next.js and Vite).
- 3D tile layers (
type="Tiles3D") load in development with React StrictMode. Before, the second mount removed the layer. - Components work in Next.js Server Components, since the package marks them
"use client". Before, renderingSphereProviderin a server layout failed withcreateContext is not a function. - The web services client works on servers with domain-restricted keys, through the new
refereroption.
New in 2.1
MarkerCluster: thousands of React markers, grouped into clusters.useSuggest: autocomplete that waits for typing to pause and ignores old responses.- The current view:
onViewChangeonSphereMap,useMapViewandgetView(). fallbackonSphereMap, shown until the map is ready.languageonSphereProvider, for every map, search, routing, web services and tag category labels.useRoute:destinationsas state, and theautooption.goToacceptsrotate, matching therotateprop andsetRotate.- Web services: the
gistda-sphere-react/servicesentry, and therefererandheadersoptions. - Types:
window.deckis typed, and map getters return their value type. - Docs: every live demo shows its full code under "Show code".
Upgrading from 1.4 to 2.0
2.0 covers the whole Sphere API and fixes several long-standing bugs. Most apps upgrade without changes, but check the changes below if you use routing, getArea, map event hooks or TAG_CATEGORIES.
Routing results
getGuide() returns Sphere's route legs, not steps, which is why turn-by-turn directions showed undefined before. Use the new steps and summary instead:
import { type RouteGuideStep } from "gistda-sphere-react";
const steps = getGuide() as RouteGuideStep[];
steps.map((step) => step.instruction); // undefinedimport { useRoute } from "gistda-sphere-react";
const { steps, summary, status, error } = useRoute();
steps.map((step) => step.instruction); // "Turn right to Sathon Nuea Rd"RouteGuideStep now describes Sphere's real step data: distance, interval, name and turn. See useRoute.
Event handler arguments
useMapEvent handlers now receive every argument Sphere sends, typed per event. For example, overlayClick handlers get (overlay, location). The explicit generic form useMapEvent<T>(…) still works but is deprecated.
Areas as text
getArea(language) on polygons, rectangles and circles returns plain text such as "120 sq.km". Before, it returned Sphere's HTML ("120 sq.km<br />74,995 rai…"). For Thai units, use formatThaiArea from useSphereUtils.
Search errors
search, suggest and nearPoi throw a descriptive error when the service returns nothing, and address resolves null when there's no address. Wrap calls in try/catch.
Tag IDs
TAG_CATEGORIES used three IDs that match no POIs. They're now "ธนาคาร/สถาบันการเงิน" (banks), "เอทีเอ็ม" (ATMs) and "สถานีบริการน้ำมัน" (gas stations). If you stored the old IDs, update them.
Fixed in 2.0
onClickon markers and shapes now fires (it never did), with the click location.lineStylenow draws dashed and dotted lines,ui="None"now hides the UI, andinput={false}now disables interaction.useMapReadynow runs its handler.languageandfilteronSphereMapupdate the map in place. You no longer needkey={language}to remount the map.- Shapes keep their identity when colors or width change, instead of being redrawn.
- Removing a
<Tag name="a|b">removes both tags. - The map's WebGL context is released when
SphereMapunmounts.
New in 2.0
- Components:
GeoJson,ObjectOverlay,PredefinedOverlay,Tag,MapControl,MenuBar,RouteGuide,SearchResults. - Hooks:
useUi,useTagCategories,useSphereUtils,useSphereServices. - Web services client (
createSphereServices) for every REST service. SphereMap:baseLayer,controls,options, livezoomRange, and a prop for every map event.- Markers and popups: React content (
children,popupContent), smooth movement (animate). - Shapes: labels, editing, spatial tests, polygon operations and measurements on refs.
Layer: MapLibre styles (heatmaps, clusters, vector tiles), 3D tiles, I3S and deck.gl layers.SphereProvider:formatPoiandpoiPopupOptionsfor POI popups.
See API coverage for the full map of the Sphere API.