GeoView is a single script, cgpv-main.js, that loads its other files (packages, workers, translations and images) from the same folder. Load it in one of two ways, then add a map container.
Official releases are hosted at https://viewer-visualiseur.services.geo.ca/apps/GeoView/{VERSION}/. Always reference a specific version so a new release cannot change your site without testing:
<script src="https://viewer-visualiseur.services.geo.ca/apps/GeoView/2.3.0/cgpv-main.js"></script>
Use this option for intranets, offline networks or strict Content Security Policies.
/geoview/). Keep the folder structure; copying cgpv-main.js alone does not work.<script src="/geoview/cgpv-main.js"></script>
Serve the files over HTTP(S). Opening the page from the file system (file://) blocks the packages and workers that GeoView loads at runtime.
Note: The bundle at https://canadian-geospatial-platform.github.io/geoview/public/cgpv-main.js is a development preview built from the develop branch. It changes with every merge and shows a -dev.<hash> version suffix; do not use it in production.
Add a <div> with the geoview-map class, load the script once, then call cgpv.init() to render the maps:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>My GeoView map</title>
</head>
<body>
<div
id="mapOne"
class="geoview-map"
style="height: 100vh;"
data-lang="en"
data-config="{ 'map': { 'interaction': 'dynamic', 'viewSettings': { 'projection': 3978 }, 'basemapOptions': { 'basemapId': 'transport', 'shaded': true, 'labeled': true } } }"
></div>
<script src="https://viewer-visualiseur.services.geo.ca/apps/GeoView/2.3.0/cgpv-main.js"></script>
<script>
cgpv.init();
</script>
</body>
</html>
The sections below describe the map container attributes and the programmatic approach in detail.
GeoView text sizes are independent of the host page’s root font size and follow the user’s browser default. Set the host’s root font size before the first map initializes: GeoView calibrates once per document and does not change the host’s root styles. This guarantee applies to calibrated GeoView themes, not standalone components using a plain external MUI theme. See typography.
There are two main approaches to create maps in GeoView:
createMapFromConfig API methodIMPORTANT NOTE If you are using a framework to inject the cgpv-main.js script dynamically, you may end up with multiples version of cgpv window object and React version. If this happen you will have a console log that says ‘Multiple instances of cgpv loaded. Make sure you only inject cgpv-main.js once.’ If this happens, try to resolve the issue by injection cgpv script only one or unmount it properly betweeen the calls.
When you call cgpv.init(), it scans the DOM for elements that are intended to host GeoView maps. It initializes all GeoView maps found in the DOM. Call this after registering your event handlers.
Specifically, it looks for <div> elements with the geoview-map class that identify them as GeoView map containers.
Typical requirements for a GeoView map container:
<div>.geoview-map.data-config, data-config-url, data-lang, data-footer-height, data-geocore-keys, or data-shared to specify map configuration, language, footer height, GeoCore layers, or shared state.data-config has precedence over data-config-url if both are provided.Example:
<div
id="myMap"
class="geoview-map"
data-lang="en"
data-config-url="path/to/config.json"
data-footer-height="50vh"
style="width: 100%; height: 400px;"
></div>
How it works:
cgpv.init() finds all such elements in the DOM.Tip:
Make sure your map container divs are present in the DOM before calling cgpv.init(), and that they have the required attributes for your use case.
GeoView maps can be configured using several HTML attributes:
data-configThe data-config attribute allows you to specify the map configuration directly as a JSON string.
<div
id="myMap"
class="geoview-map"
data-lang="en"
data-config='{"layers":[{"id":"osm","name":"OpenStreetMap","url":"https://tile.openstreetmap.org/{z}/{x}/{y}.png","type":"osm"}],"initialView":{"zoom":4,"center":[-100,60]}}'
style="width: 100%; height: 400px;"
></div>
data-config-urlThe data-config-url attribute specifies a URL to a JSON configuration file. This is useful for larger configurations or when you want to reuse the same configuration across multiple maps.
<div
id="myMap"
class="geoview-map"
data-lang="en"
data-config-url="configs/map-config.json"
style="width: 100%; height: 400px;"
></div>
The JSON file should have the same structure as the inline data-config value.
data-footer-heightThe data-footer-height attribute allows for manually setting the expanded footer panel height so that it is not default 600px or the same height as the map. The value can be any css height value although pixels (px) and view height (vh) are recommended. This attribute does not set the height of the collapsed footer header; the collapsed header is automatically accounted for inside the map container’s explicit height.
<div
id="myMap"
class="geoview-map"
data-lang="en"
data-footer-height="450px"
data-config-url="configs/map-config.json"
style="width: 100%; height: 400px;"
></div>
data-geocore-keysThe data-geocore-keys attribute allows you to inject GeoCore layers by UUID directly on the div element, without including them in the main configuration object. Multiple UUIDs are separated by commas.
<div
id="myMap"
class="geoview-map"
data-lang="en"
data-geocore-keys="12acd145-626a-49eb-b850-0a59c9bc7506,ccc75c12-5acc-4a6a-959f-ef6f621147b9"
data-config-url="configs/map-config.json"
style="width: 100%; height: 400px;"
></div>
The specified GeoCore layers are appended to any layers already defined in data-config or data-config-url.
data-sharedWhen set, the map will load configuration from URL parameters if they are present. This is especially useful for sharing specific map views or configurations via links.
Demo: demo-share.html
When data-shared is used together with data-config or data-config-url, the base configuration from those attributes is preserved, and URL parameters selectively override specific properties:
p) — overrides viewSettings.projectionz, c) — overrides viewSettings.initialView.zoomAndCenterb) — overrides basemapOptionskeys) — appended to existing config layers, not replaced<div
id="myMap"
class="geoview-map"
data-lang="en"
data-shared
style="width: 100%; height: 400px;"
></div>
With this setup, you can share a link with URL parameters to load a specific map configuration.
Example URL with parameters:
https://example.com/geoview/default-config.html?p=3857&z=4&c=-100,40&b=id:transport,s:off,l:on&i=dynamic&keys=12acd145-626a-49eb-b850-0a59c9bc7506,ccc75c12-5acc-4a6a-959f-ef6f621147b9
Supported URL parameters:
| Parameter | Description | Example Values |
|---|---|---|
z |
Zoom level | 4 |
p |
Projection code | 3857, 3978 |
c |
Center coordinates [longitude, latitude] | -100,40 |
b |
Basemap options | id:transport,s:off,l:on |
i |
Interaction type | dynamic, static |
keys |
GeoCore layer UUID keys (comma separated) | 12acd145-626a-49eb-b850-0a59c9bc7506,ccc75c12-5acc-4a6a-959f-ef6f621147b9 |
v |
Schema version | 1.0 |
How it works:
geoview-map classdata-shareddata-shared is present, the map will load the configuration from the URL parametersdata-shared, all of them will use the same URL parameters configurationThe configuration object (whether provided via data-config or data-config-url) follows the general structure provided by the geoview-core/schema.json file.
For detailed configuration options, refer to the GeoView configuration documentation or example configuration files in the project.
You can also create maps programmatically using the createMapFromConfig method from the API. This is useful when you need to create maps dynamically or when you want more control over the creation process.
Full API Reference: API — TypeDoc
Important Note: The div MUST NOT have a geoview-map class. If it does, an InitMapWrongCallError will be thrown. The class is added automatically by the framework.
Example Usage:
// Create a div element
const mapDiv = document.createElement("div");
mapDiv.id = "dynamicMap";
document.body.appendChild(mapDiv);
// Configuration can be a JSON string or a URL to a config file
const mapConfig = JSON.stringify({
// Your map configuration
});
// Create the map (awaits map ready by default)
const mapViewer = await cgpv.api.createMapFromConfig(
"dynamicMap",
mapConfig,
500,
);
console.log("Map created successfully:", mapViewer.mapId);
// Or without waiting for map ready
const mapViewer2 = await cgpv.api.createMapFromConfig(
"dynamicMap2",
mapConfig,
500,
false,
);
When to use this approach:
// Register a handler when the map is initialized
cgpv.onMapInit((mapViewer) => {
// This callback is executed when map is init. The layers have NOT been registered yet at this time.
// If you want to track ALL status changes for ANY particular layer, use:
// `mapViewer.layer.onLayerStatusChanged()`
console.log("Map initialized:", mapViewer.mapId);
// Listen to ANY/ALL layer status at ANY time (generic event catcher)
mapViewer.layer.onLayerStatusChanged((sender, payload) => {
console.log(
`LayerApi: ${payload.config.layerPath} (generic event) status changed to ${payload.status}`,
);
});
});
// Register a handler when the map is ready (map and UI are fully loaded)
cgpv.onMapReady((mapViewer) => {
// This callback is executed when map is ready / ALL layers have at least been registered.
// NOTE: some layers can be further along in their individual status at the time this event is triggered(!)
console.log("Map ready for interaction:", mapViewer.mapId);
});
These events are important for proper initialization sequencing:
onMapInit — Fires when the map object is first initialized, but before layers are processedonMapReady — Fires when the map and UI are fully loaded and ready for interaction (note: layers might not be ready)Using these events helps you properly sequence your application’s initialization logic.
Full API Reference: API — TypeDoc
The cgpv.api.maps property is private. Use the following methods to access and interact with maps:
// Get a list of all active map IDs
const mapIds = cgpv.api.getMapViewerIds(); // string[]
// Check if a map exists
const exists = cgpv.api.hasMapViewer("Map1"); // boolean
// Get a map viewer by ID (throws MapViewerNotFoundError if not found)
const mapViewer = cgpv.api.getMapViewer("Map1");
mapViewer.layer.addGeoviewLayerByGeoCoreUUID(layer);
// Get a map viewer asynchronously (waits until available)
const mapViewer = await cgpv.api.getMapViewerAsync("Map1");
// Delete a map instance
// deleteContainer: true removes the div from the DOM, false keeps it for reuse
await cgpv.api.deleteMapViewer("Map1", false);