Optional XYZ tile layers
CanvasGlobe ships its country geometry inside the package and makes no required network request.
Use tileLayer only when your product needs satellite imagery, a branded basemap, weather tiles,
or another raster source that the bundled vector geography cannot provide.
The demo below generates four tiles in the browser. It proves the same provider API without sending data to a third party. Switch between globe and map views to see one cached raster reprojected by CanvasGlobe.
Provider configuration
url accepts {z}, {x}, {y}, and {-y} placeholders. If a URL template is not enough, use
getTile({ x, y, z }) and return a URL, canvas, image, bitmap, or a Promise of one.
| Field | Default | Purpose |
|---|---|---|
url | Not set | XYZ URL template |
getTile | Not set | Custom, signed, generated, or offline tile provider |
zoom | 2 | Fixed overview zoom used to build the raster |
tileSize | 256 | Source tile width and height |
maxWidth | 2048 | Maximum composed texture width |
maxTiles | 64 | Hard request ceiling; allows up to zoom 3 by default |
opacity | 1 | Raster opacity |
attribution | Empty | Provider credit painted into the canvas and exports |
crossOrigin | "anonymous" | CORS mode for URL images; use null only when appropriate |
onError | Not set | Receives (error, tile) without stopping the render loop |
CanvasGlobe requests each XYZ coordinate once for the lifetime of the layer. A failed tile leaves
the built-in background visible. Calling setTileLayer(null) releases the cache.
CORS, export, and provider terms
Globe reprojection and image export must read tile pixels. A remote provider therefore needs to
return a compatible Access-Control-Allow-Origin header. Without it, the browser protects the
pixels and CanvasGlobe cannot reproject or export that raster.
Always use the attribution, access token, licence, usage policy, and request limits required by your provider. The library does not include, proxy, or silently select a third-party tile service.
When not to use tile layers
Keep the default bundled geography when you only need countries, dots, routes, markers, charts, or marketing visuals. It starts faster, works offline, avoids provider costs, and has no attribution or token requirement. CanvasGlobe tile layers are intentionally optimized for global and regional overviews. Use a dedicated slippy-map engine for street-level navigation, continuously changing zoom levels, vector-tile styling, terrain, or very large geospatial datasets.