Getting Started

This guide introduces you to the basic principles of building a map and helps you get up and running with MapWeave. We are going to embed MapWeave in an HTML page and add data and layers.

Creating an App

Firstly, you need to create a local app for the MapWeave component. You can create one with Vite which will be shown in this guide, or another build tool of your choice. If you have an existing app, move on to Installing MapWeave.

npm
Yarn
pnpm

npm init vite@latest my-mapweave-app -- --template vanilla

yarn create vite my-mapweave-app --template vanilla

pnpm create vite my-mapweave-app --template vanilla

Once this process has completed, you can start your app:

npm
Yarn
pnpm

cd my-mapweave-app
npm install
npm run dev

cd my-mapweave-app
yarn install
yarn dev

cd my-mapweave-app
pnpm install
pnpm run dev

By default, Vite runs a development server at http://localhost:5173.

Installing MapWeave

Download the latest version of MapWeave.

Latest Release

Request a trialOctober 3, 2025

The download contains a package.json file referencing external dependencies as well as a pre-built set of bundled dependencies. See the dependencies page for more information.

Move the downloaded file into your project's root folder.

Then install the file from inside your project's root folder:

npm
Yarn
pnpm

npm install file:<<< your_downloaded_file_name >>>

yarn add file:<<< your_downloaded_file_name >>>

pnpm add file:<<< your_downloaded_file_name >>>

Now we have a local app and MapWeave is installed.

Making an HTML Page

You need to replace the content in the Vite generated HTML and CSS files to add a <div> for the MapWeave component and style it appropriately.

Replace the content of index.html with the following code. It contains a <div> that has been assigned an id of "mw":

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="stylesheet" href="src/style.css" />
    <script type="module" src="src/main.js"></script>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>MapWeave App</title>
  </head>
  <body>
    <div id="mw"></div>
  </body>
</html>

Then replace the content of src/style.css with these styles:

src/style.css
#mw {
  height: 100vh;
}

body {
  margin: 0;
}

Now we have an empty page and are ready to add the MapWeave component.

Adding a Map Adapter

MapWeave provides the option to use an adapter for a 3rd party map provider such as Mapbox or MapLibre.

Instructions for each adapter are shown below, you only need to follow the steps for the adapter you are using. Follow these steps exactly if you are creating a new app with Vite.

Ensure you check the terms and conditions of any 3rd party dependency you use.

Mapbox

Mapbox supports vector tiles and requires an access token.

Install the Mapbox package into your project folder as follows:

npm
Yarn
pnpm

npm install mapbox-gl

yarn add mapbox-gl

pnpm add mapbox-gl

Next import MapWeave and the relevant css into src/main.js, create a new MapWeave object and assign the container. Add the access token to the MapWeaveOptions interface. You also need to specify a tileset, the options can be found in the Mapbox styles API docs.

info

We recommend securing your Mapbox access token by storing it as an environment variable. For more information about how to set up environment variables with Vite, please see https://vite.dev/guide/env-and-mode.

src/main.js
import { MapWeave } from 'mapweave/mapbox';
import 'mapbox-gl/dist/mapbox-gl.css';

const mapweave = new MapWeave({
  container: 'mw', // this is the id of the div in index.html
  options: {
    accessToken: 'YOUR_ACCESS_TOKEN_GOES_HERE', // add your Mapbox API key here
    style: 'mapbox://styles/mapbox/light-v11', // add your tileset link here
  },
});

You can also look at the Mapbox example.

MapLibre

If no tileset is specified, MapLibre adapter uses default tiles. More information can be found in the MapLibre style spec.

To use the MapLibre adapter, install the package into your project folder as follows:

npm
Yarn
pnpm

npm install maplibre-gl

yarn add maplibre-gl

pnpm add maplibre-gl

Next, replace the code in src/main.js to import MapWeave and the relevant css, create a new MapWeave object and assign the container:

src/main.js
import { MapWeave } from 'mapweave/maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

const mapweave = new MapWeave({
  container: 'mw', // this is the id of the div in index.html
});

You can also look at the MapLibre example.

Standalone

MapWeave can be used without any 3rd party basemap library to minimize dependencies. This approach supports raster tiles only.

To use this option import MapWeave into src/main.js, create a new MapWeave object and assign the container. Then create a new TileLayer and add the link to the map tiles. This example uses OpenStreetMap.

src/main.js
import { MapWeave } from 'mapweave/standalone';
import { TileLayer } from 'mapweave/layers';
import 'mapweave/mapweave.css';

const mapweave = new MapWeave({
  container: 'mw', // this is the id of the div in index.html
});

mapweave.addLayer(
  new TileLayer({
    data: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
  }),
);

You can also look at the Standalone example.

Centering the map

For this guide the example data is for Downtown Vancouver, so this is where you would need to center the map.

Specify the latitude and longitude for the center of the map and the zoom level and pass it to mapweave.view().

src/main.js
const defaultView = {
  latitude: 49.28,
  longitude: -123.12,
  zoom: 13,
};

mapweave.view(defaultView);

The example below, using the Mapbox adapter, shows what the result will look like once the map is centered:

Adding Layers

info

The code examples and screenshots in this section are using the Mapbox adapter.

MapWeave provides layers to add different kinds of data depending on the use case. You can use as many layers as you need. Layers are rendered in the order that they are specified, so the layer that is defined first will be rendered first.

The layers available are:

The Network Layer, which allows for the addition of a graph with either linked or unlinked nodes.
The Observations Layer, which allows entities to be tracked via locations and time.
The GeoJSON Layer, which allows geographical data to be added using the GeoJSON open standard.

Network Layer

In this example car charging stations are fixed nodes (nodes that are at a specific location) and their owners as free nodes (nodes that do not have a location). The links denote who owns which charging station.

First, import the NetworkLayer into the src/main.js file.

src/main.js
import { NetworkLayer } from 'mapweave/layers';

Add meaning to the graph by defining some simple colors for the fixed and free nodes as well as link, text and label colors.

const linkColor = '#FD9067';
const textColor = '#F4F4F5';
const labelColor = '#6E7379';
const freeNodeColor = '#FD9067';
const fixedNodeColor = '#774299';

Add the charging stations data object. For more information on this data object, see the NetworkLayerData API.

The data object can be added directly into src/main.js or imported from a separate data file.

Expand to see the charging stations object.

const chargingStations = {
  Hamilton: {
    // fixed node
    type: 'node',
    color: fixedNodeColor,
    latitude: 49.279516,
    longitude: -123.115166,
    label: {
      text: '775 Hamilton St',
      color: textColor,
      backgroundColor: labelColor,
    },
  },
  Easypark: {
    // free node
    type: 'node',
    color: freeNodeColor,
    label: {
      text: 'Easypark',
      color: textColor,
      backgroundColor: labelColor,
    },
  },
  Mainland: {
    // fixed node
    type: 'node',
    color: fixedNodeColor,
    latitude: 49.27684,
    longitude: -123.11887,
    label: {
      text: '959-979 Mainland St',
      color: textColor,
      backgroundColor: labelColor,
    },
  },
  Vancouver: {
    // free node
    type: 'node',
    color: freeNodeColor,
    label: {
      text: 'City of Vancouver',
      color: textColor,
      backgroundColor: labelColor,
    },
  },
  Beach: {
    // fixed node
    type: 'node',
    color: fixedNodeColor,
    latitude: 49.272594,
    longitude: -123.12836,
    label: {
      text: '456 Beach Crescent',
      color: textColor,
      backgroundColor: labelColor,
    },
  },
  Richards: {
    // fixed node
    type: 'node',
    color: fixedNodeColor,
    latitude: 49.279403,
    longitude: -123.118908,
    label: {
      text: '860 Richards St',
      color: textColor,
      backgroundColor: labelColor,
    },
  },
  Georgia: {
    // fixed node
    type: 'node',
    color: fixedNodeColor,
    latitude: 49.283672,
    longitude: -123.1173,
    label: {
      text: '701 W. Georgia St.',
      color: textColor,
      backgroundColor: labelColor,
    },
  },
  Granville: {
    // fixed node
    type: 'node',
    color: fixedNodeColor,
    latitude: 49.277692,
    longitude: -123.124668,
    label: {
      text: '1100 Granville St',
      color: textColor,
      backgroundColor: labelColor,
    },
  },
  BestWestern: {
    // free node
    type: 'node',
    color: freeNodeColor,
    label: {
      text: 'Best Western',
      color: textColor,
      backgroundColor: labelColor,
    },
  },
  link1: {
    type: 'link',
    color: linkColor,
    id1: 'Easypark',
    id2: 'Hamilton',
  },
  link2: {
    type: 'link',
    color: linkColor,
    id1: 'Vancouver',
    id2: 'Mainland',
  },
  link3: {
    type: 'link',
    color: linkColor,
    id1: 'Vancouver',
    id2: 'Beach',
  },
  link4: {
    type: 'link',
    color: linkColor,
    id1: 'Vancouver',
    id2: 'Richards',
  },
  link5: {
    type: 'link',
    color: linkColor,
    id1: 'Easypark',
    id2: 'Georgia',
  },
  link6: {
    type: 'link',
    color: linkColor,
    id1: 'BestWestern',
    id2: 'Granville',
  },
};

Finally, load the data into the NetworkLayer:

src/main.js
mapweave.addLayer(
  new NetworkLayer({
    data: chargingStations,
  }),
);

MapWeave with network layer data looks like this:

For more information about graphs, nodes and links, take a look at the Basic Nodes and Links example, or read the Network Layer docs.

Observations Layer

The data passed to this layer takes the form of observations.

An observation is a record of an entity, a moving object, being observed in a particular place at a particular time.

Once observations have been loaded, MapWeave can generate trajectories showing the path taken by the entity between individual observations.

In this example, observations refer to the timestamp and location of a vehicle.

In this example, we are tracking a vehicle as it moves through the city.

First, import the ObservationsLayer into our src/main.js file.

src/main.js
import { ObservationsLayer } from 'mapweave/layers';

Next, set a color for the observations.

const observationColor = '#774299';

Add the observations data object. For more information on this data object, see the ObservationsLayerData API.

The data object can be added directly into src/main.js or imported from a separate data file.

Expand to see the vehicle observations object.

const vehicleObservations = {
  entities: { vehicle1: { color: observationColor } },
  observations: {
    vehicle1_1: {
      type: 'observation',
      entityId: 'vehicle1',
      latitude: 49.2827,
      longitude: -123.1207,
      time: new Date('2024-12-16T08:00:00'),
    },
    vehicle1_2: {
      type: 'observation',
      entityId: 'vehicle1',
      latitude: 49.2835,
      longitude: -123.1167,
      time: new Date('2024-12-16T08:05:00'),
    },
    vehicle1_3: {
      type: 'observation',
      entityId: 'vehicle1',
      latitude: 49.284,
      longitude: -123.1123,
      time: new Date('2024-12-16T08:10:00'),
    },
    vehicle1_4: {
      type: 'observation',
      entityId: 'vehicle1',
      latitude: 49.2832,
      longitude: -123.1085,
      time: new Date('2024-12-16T08:15:00'),
    },
    vehicle1_5: {
      type: 'observation',
      entityId: 'vehicle1',
      latitude: 49.2808,
      longitude: -123.106,
      time: new Date('2024-12-16T08:20:00'),
    },
  },
};

Load the observations data into a new ObservationsLayer and configure the options in the ObservationsLayerOptions.

The radiusPixels is specified to adjust the size of the dots for each observation.

By default, MapWeave will connect any observations that are equal to or less than one minute apart into a trajectory. Because the observations in the data are five minutes apart, we need to set the trajectory maximumInterval to five minutes in milliseconds.

src/main.js
mapweave.addLayer(
  new ObservationsLayer({
    data: vehicleObservations,
    options: {
      individual: { radiusPixels: 5 },
      trajectory: {
        maximumInterval: 60 * 5 * 1000,
      },
    },
  }),
);

The map then looks like this:

For more information, see the Observations and Trajectories example, or read the Observations Layer docs.

GeoJSON Layer

In this example, GeoJSON is used to highlight the downtown area of the city.

First, import the GeoJsonLayer into the src/main.js file.

src/main.js
import { GeoJsonLayer } from 'mapweave/layers';

Set a color for the GeoJSON layer. Here an rgba value is used so the shaded area can be transparent.

const geoColor = 'rgba(253, 144, 103, 0.3)';

Create the GeoJSON data object. For more information on this data object, see the GeoJSONLayerData API.

The data object can be added directly into src/main.js or imported from a separate data file.

Expand to see the Vancouver downtown object.

const vancouverDowntown = {
 type: "FeatureCollection",
 features: [
   {
     type: "Feature",
     geometry: {
       coordinates: [
         [
           [-123.112266, 49.290164],
           [-123.104240, 49.288166],
           [-123.099288, 49.289272],
           [-123.099998, 49.272750],
           [-123.101699, 49.272972],
           [-123.111076, 49.272926],
           [-123.114448, 49.271774],
           [-123.121162, 49.269538],
           [-123.129280, 49.269531],
           [-123.137680, 49.275318],
           [-123.132331, 49.276931],
           [-123.121093, 49.284366],
           [-123.136680, 49.294456],
           [-123.134689, 49.295810],
           [-123.122711, 49.291500],
           [-123.112266, 49.290164],
         ],
       ],
       type: "Polygon",
     },
     properties: { color: geoColor },
   },
 ],
};

Load that data into a new GeoJsonLayer.

src/main.js
mapweave.addLayer(
  new GeoJsonLayer({
    data: vancouverDowntown,
  }),
);

MapWeave with GeoJSON layer data looks like this:

For more information, see the Load Data example, or read the GeoJSON Layer docs.

Creating an App​

Installing MapWeave​

Latest Release

Making an HTML Page​

Adding a Map Adapter​

Mapbox​

MapLibre​

Standalone​

Centering the map​

Adding Layers​

Network Layer​

Observations Layer​

GeoJSON Layer​

Creating an App

Installing MapWeave

Making an HTML Page

Adding a Map Adapter

Mapbox

MapLibre

Standalone

Centering the map

Adding Layers

Network Layer

Observations Layer

GeoJSON Layer