Guides

This section of the docs' site is dedicated to some more complex examples and tutorials. If you have something you would like to share with the community that is not straight forward and might be beneficial to others, this is the place!

Things that are short enough and/or with lower complexity are probably already in the Examples section, but if not, feel free to add there.

The process of adding examples or guides is pretty straight forward, see our docs folder in the MapVina GL JS repo for more information.

Introduction

MapVina GL JS is a TypeScript library that uses WebGL to render interactive maps from vector tiles in the browser. Maps are styled using the MapVina Style Spec. Part of the MapVina ecosystem, with native versions for Android/iOS at MapVina Native.

Quickstart

<div id="map"></div>
<script>
    var map = new mapvinagl.Map({
        container: 'map',
        style: 'https://maps.mapvina.com/styles/v2/streets.json?key=public_key',
        center: {"lat": 10.769034, "lng": 106.694945},
        zoom: 9
    });
</script>

List style

V2:

Streets: https://maps.mapvina.com/styles/v2/streets.json?key=public_key
A detailed and vibrant map style for urban navigation and general use.
Night: https://maps.mapvina.com/styles/v2/night.json?key=public_key
A dark-themed style optimized for low-light conditions or nighttime viewing.
Simple: https://maps.mapvina.com/styles/v2/simple.json?key=public_key
A minimalist map style for clean and uncluttered visualization.
Streets Raster: https://maps.mapvina.com/styles/v2/streets-raster.json?key=public_key
A raster-based version of the streets style.

V1: Former administrative unit

Streets: https://maps.mapvina.com/styles/v1/streets.json?key=public_key
A detailed and vibrant map style for urban navigation and general use.
Night: https://maps.mapvina.com/styles/v1/night.json?key=public_key
A dark-themed style optimized for low-light conditions or nighttime viewing.
Simple: https://maps.mapvina.com/styles/v1/simple.json?key=public_key
A minimalist map style for clean and uncluttered visualization.

Style detail level (detailLevel)

The detailLevel parameter controls the level of detail for places displayed on the map.

Supported values

none: Shows only the base map.
basic (default): Shows common and essential places.
enhanced: Shows both basic and extended places.
full: Shows all available places.

Usage

Pass the detailLevel parameter in the style URL.

https://maps.mapvina.com/styles/v2/streets.json?detailLevel=enhanced&key=public_key

Reading this documentation

This documentation is divided into several sections:

Main - The Main section holds the following classes
- Map object is the map on your page. It lets you access methods and properties for interacting with the map's style and layers, respond to events, and manipulate the user's perspective with the camera.
- Global Functions let you set global properties and options that you might want to access while initializing your map or accessing information about its status.
Markers and Controls - This section describes the user interface elements that you can add to your map. The items in this section exist outside of the map's canvas element. This consists of Marker, Popup and all the controls.
Geography and geometry - This section includes general utilities and types that relate to working with and manipulating geographic information or geometries.
User interaction handlers - The items in this section relate to the ways in which the map responds to user input.
Sources - This section describes the source types MapVina GL JS can handle besides the ones described in the MapVina Style Specification.
Event Related - This section describes the different types of events that MapVina GL JS can raise.

Each section describes classes or objects as well as their properties, parameters, instance members, and associated events. Many sections also include inline code examples and related resources.

NPM

Install the MapVina GL JS package via NPM.

npm install mapvina-gl

You can then import the MapVina GL JS module in your project.

<div id="map"></div>

import mapvinagl from 'mapvina-gl';
import 'mapvina-gl/dist/mapvina-gl.css';

const map = new mapvinagl.Map({
    container: 'map', // container id
    style: 'https://maps.mapvina.com/styles/v2/streets.json?key=public_key', // style URL
    center: {"lat": 10.769034, "lng": 106.694945}, // starting position [lng, lat]
    zoom: 9 // starting zoom
});

CSP Directives

As a mitigation for Cross-Site Scripting and other types of web security vulnerabilities, you may use a Content Security Policy (CSP) to specify security policies for your website. If you do, MapVina GL JS requires the following CSP directives:

worker-src blob: ;
child-src blob: ;
img-src data: blob: ;

For strict CSP environments without worker-src blob: ; child-src blob: enabled, there's a separate MapVina GL JS bundle (mapvina-gl-csp.js and mapvina-gl-csp-worker.js) which requires setting the path to the worker manually:

<script>
mapvinagl.setWorkerUrl("${urls.js().replace('.js', '-csp-worker.js')}");
...
</script>

MapVina CSS

The CSS referenced in the Quickstart is used to style DOM elements created by MapVina code. Without the CSS, elements like Popups and Markers won't work.

Including it with a <link> in the head of the document via the UNPKG CDN is the simplest and easiest way to provide the CSS, but it is also bundled in the MapVina module, meaning that if you have a bundler that can handle CSS, you can import the CSS from mapvina-gl/dist/mapvina-gl.css.

Note too that if the CSS isn't available by the first render, as soon as the CSS is provided, the DOM elements that depend on this CSS should recover.

CDN

MapVina GL JS is also distributed via UNPKG. Our latest version can installed by adding below tags this in the html <head>. Further instructions on how to select specific versions and semver ranges can be found on at unpkg.com.

<script src="https://unpkg.com/mapvina-gl@latest/dist/mapvina-gl.js"></script>
<link href="https://unpkg.com/mapvina-gl@latest/dist/mapvina-gl.css" rel="stylesheet" />