Layer
Built-in data layers, WMS/WMTS/TMS/XYZ tiles, vector styles, heatmaps, 3D tiles and deck.gl layers
<Layer> adds a layer while it's mounted and removes it when it unmounts. It covers Sphere's built-in layers, standard tile services, MapLibre styles and 3D data.
import { Layer, SphereMap } from "gistda-sphere-react";
<SphereMap baseLayer="STREETS">
<Layer preset="TRAFFIC" />
<Layer name="bluemarble_terrain" type="WMS" url="https://ms.longdo.com/mapproxy/service" opacity={0.6} />
</SphereMap>Props
Use one of preset, name, style or layer to choose what to show.
| Prop | Type | Description |
|---|---|---|
preset | BuiltInLayer | A built-in Sphere layer, e.g. "TRAFFIC". |
name | string | Name of a raster or 3D layer. For WMS this is the WMS layer name. |
type | LayerType | "Vector" (default), "XYZ", "WMS", "WMTS", "WMTS_REST", "TMS", "Tiles3D" or "I3S". |
url | string | Tile server or tileset URL. |
style | string | object | A MapLibre style object or style URL: vector tiles, heatmaps, clusters and other MapLibre layers. |
layer | object | A ready-made layer added as is: a sphere.Layer, a deck.gl MapboxLayer or a MapLibre layer object. |
isBase | boolean | Use as the base map instead of adding on top. Prefer SphereMap's baseLayer. |
opacity | number | 0 to 1. |
zIndex | number | Layers with a higher zIndex draw above lower ones. |
zoomRange | Range | Zoom levels where the layer is visible. |
source | Range | Zoom levels the tile server has. |
bound | Bound | Only request tiles inside this box. |
attribution | string | Attribution text. |
beforeId | string | Insert below this MapLibre layer ID (default: below the map labels). |
extraQuery | string | Extra query string for tile requests, e.g. "TIME=2024-01-01". |
format | string | false | WMS/WMTS: image MIME type (default image/png). XYZ/TMS/WMTS_REST: file extension (default png). false leaves it out. |
srs | string | WMS spatial reference or WMTS tile matrix set (default EPSG:3857). |
styles | string | WMS/WMTS styles. |
version | string | WMS version (default 1.1.1). |
tileMatrixPrefix | string | WMTS: part of the tile matrix name before the zoom level. |
loadOptions | object | Tiles3D/I3S: loaders.gl options under 3d-tiles, i3s or tileset. |
pointSize | number | Tiles3D point clouds: point radius in pixels. |
onTilesetLoad | (tileset) => void | Tiles3D/I3S: called once the tileset loads, with its cartographicCenter and zoom. |
id | string | Unique layer ID (default: the name). |
options | Record<string, unknown> | Extra options for new sphere.Layer(). |
Built-in layers
| Base maps | Data layers | ||
|---|---|---|---|
SIMPLE | Simple map | TRAFFIC | Live traffic (refreshes every 3 minutes) |
STREETS | Streets (default) | PM25 | PM2.5 air quality |
STREETS_NIGHT | Streets, dark theme | HOTSPOT | Fire hotspots |
HYBRID | Satellite with labels | FLOOD | Flood areas |
IMAGES | Satellite imagery | DROUGHT | Drought areas |
import { Layer } from "gistda-sphere-react";
<Layer preset="PM25" />Set the base map with SphereMap's baseLayer prop.
Tile services
import { Layer } from "gistda-sphere-react";
{/* WMS */}
<Layer
name="bluemarble_terrain"
type="WMS"
url="https://ms.longdo.com/mapproxy/service"
opacity={0.7}
/>
{/* WMTS (key-value) */}
<Layer name="my_layer" type="WMTS" url="https://example.com/wmts" srs="EPSG:3857" />
{/* XYZ from Sphere's own raster server (the default url) */}
<Layer name="thailand_images" type="XYZ" srs="EPSG3857" format="jpeg" />
{/* XYZ from another server: requests https://tiles.example.com/osm/{z}/{x}/{y}.png */}
<Layer name="osm" type="XYZ" url="https://tiles.example.com" />For XYZ and TMS, Sphere builds tile URLs as {url}/{name}/{srs}/{z}/{x}/{y}.{format}, leaving out srs when it isn't set. Pass format={false} when the server's URLs have no extension.
See Custom WMS layer for a complete example.
MapLibre styles: heatmaps, clusters and vector tiles
style takes a MapLibre style object (or URL). Give its sources IDs that don't clash with other layers:
import { Layer } from "gistda-sphere-react";
<Layer
style={{
sources: {
quakes: { type: "geojson", data: "https://example.com/earthquakes.geojson" },
},
layers: [{ id: "quakes-heat", type: "heatmap", source: "quakes" }],
}}
/>The 3D and advanced layers guide shows heatmaps, clustering and 3D data in action.
3D tiles and I3S
import { Layer } from "gistda-sphere-react";
<Layer
name="buildings"
type="Tiles3D"
url="https://raw.githubusercontent.com/CesiumGS/3d-tiles-samples/main/1.0/TilesetWithRequestVolume/tileset.json"
onTilesetLoad={(tileset) => {
const [lon, lat] = tileset.cartographicCenter ?? [];
goTo({ center: { lon, lat }, zoom: (tileset.zoom ?? 13) + 3, pitch: 60 });
}}
/>type="Tiles3D" loads OGC 3D Tiles (tileset.json), such as these sample buildings from Cesium. For point clouds, set pointSize, and options={{ getPointColor: [37, 99, 235, 255] }} when the points have no colors of their own (deck.gl draws them black). Everything in options goes to deck.gl's Tile3DLayer.
type="I3S" is part of Sphere's API, but Sphere's current runtime can't draw I3S meshes: the tileset loads, then deck.gl reports an error on every frame and nothing appears. Use 3D Tiles until GISTDA fixes it.
deck.gl and raw MapLibre layers
Sphere bundles deck.gl and puts it on window.deck. Wrap a deck.gl layer in deck.MapboxLayer and pass it as layer:
import { Layer } from "gistda-sphere-react";
import { useMemo } from "react";
const model = useMemo(() => {
const { deck } = window;
if (!deck) {
return null;
}
return new deck.MapboxLayer({
id: "model",
type: deck.ScenegraphLayer,
data: [{ position: [100.5, 13.7, 0] }],
getPosition: (d: { position: number[] }) => d.position,
scenegraph: "https://example.com/model.glb",
});
}, []);
{model && <Layer layer={model} />}window.deck is typed as optional, because it only exists once Sphere's script has loaded, so check it first. Inside SphereMap it's always there, since children render once the map is ready. Its members are typed loosely (DeckNamespace), so type your accessors' arguments yourself, as with d above.
Create layer objects once (with useMemo) or outside the component. A new object on every render re-adds the layer each time.
refresh and zoomOffset are also accepted and passed to Sphere unchanged.