Terra Draw adds a number of geographical Feature drawing tools to popular mapping libraries. There are few key concepts that allow it to stay strongly decoupled and as library-agnostic as possible, let's walk through them.
The Store is the heart of the library and is responsible for managing the state of all Features that are added to the map. The Store is created when Terra Draw is instantiated:
// Create a Terra Draw instance and assign it to a variable called `draw`
const draw = new TerraDraw({ adapter, modes });Important
Throughout the documentation we will use the variable name draw to refer to the Terra Draw instance.
Features are added to the Store when interacting with the Map using a number of available drawing Modes (such as TerraDrawRectangleMode or TerraDrawPolygonMode).
The Store is exposed via the getSnapshot method, which returns an Array of all given Feature geometries in the Store:
// Get an Array of all Features in the Store
const features = draw.getSnapshot();See the Store section to find out more about the store and getting data in and out of Terra Draw.
Adapters are thin wrappers that contain map library specific logic, for creating and updating layers rendered by the mapping library. Terra Draw supports a series of Adapters out of the box, with a series of packages within this monorepo. Currently supported are: Leaflet, OpenLayers, Mapbox GL JS, MapLibre GL JS, Google Maps JS API and the ArcGIS JS SDK.
Let's say as an example you are using Leaflet, you would install the Leaflet adapter (TerraDrawLeafletAdapter) in the following way:
npm install terra-draw-leaflet-adapterAnd then in your code you would import it like so:
import { TerraDrawLeafletAdapter } from 'terra-draw-leaflet-adapter';
// Create an Adapter for Leaflet
const adapter = new TerraDrawLeafletAdapter({ map, lib });See the Adapters section for more information on the different adapters for different mapping libraries.
Modes represent the logic for a specific drawing tool, for example there are TerraDrawRectangleMode, TerrDrawPolygonMode and TerraDrawLineStringMode Modes which allow you to draw rectangles, polygons and lines on the map respectively.
The TerraDrawSelectMode allows for the selection and manipulation of features on the Map, while the TerraDrawRenderMode is used to render uneditable features, for example contextual data.
Modes are instantiated like so:
const polygonMode = new TerraDrawPolygonMode();
const rectangleMode = new TerraDrawRectangleMode();
const renderMode = new TerraDrawRenderMode({
modeName: "auniquename",
});See the Modes section for more information. For information regarding touch support, see Touch Device Support.
Terra Draw can be added to your site either via the <script> tag, or using a package manager like NPM.
Important
We start with the assumption that you have both Node.js and npm installed.
You can install the Terra Draw into your project like so:
npm install terra-drawView the npm terra-draw package page for more information.
You will need an adapter as well, to connect your mapping library to Terra Draw. Let's install the MapLibre adapter:
npm install terra-draw-maplibre-gl-adapterView the npm terra-draw-maplibre-gl-adapter page for more information.
Once installed via NPM you can use Terra Draw in your project like so:
// Import Terra Draw
import { TerraDraw, TerraDrawRectangleMode } from "terra-draw";
import { TerraDrawMapLibreGLAdapter } from 'terra-draw-maplibre-gl-adapter
// Import MapLibreGL
import { MapLibreGL as lib } from "maplibre-gl";
// Create MapLibre Map, targeting <div id="map">
const map = new MapLibreGL.Map({ container: "map" });
// Create Terra Draw
const draw = new TerraDraw({
// Using the MapLibre Adapter
adapter: new TerraDrawMapLibreGLAdapter({ map, lib }),
// Add the Rectangle Mode
modes: [new TerraDrawRectangleMode()],
});
// Start drawing
draw.start();
draw.setMode("rectangle");To use Terra Draw without a build step, you can load the UMD (Universal Module Definition) bundle directly from a CDN (Content Delivery Network) like unpkg.
For example if we were using Terra Draw with MapLibre we might do something like this in our <head> tag:
<!-- MapLibre -->
<script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>
<link
href="https://unpkg.com/[email protected]/dist/maplibre-gl.css"
rel="stylesheet"
/>
<!-- Terra Draw -->
<script src="https://unpkg.com/[email protected]/dist/terra-draw.umd.js"></script>
<script src="https://unpkg.com/[email protected]/dist/terra-draw-maplibre-gl-adapter.umd.js"></script>Later on in our JavaScript code we can access terraDraw globally like so:
const TerraDraw = terraDraw.TerraDraw
const TerraDrawMapLibreGLAdapter = terraDrawMapLibreGLAdapter.TerraDrawMapLibreGLAdapter
// Create Terra Draw instance
const draw = new TerraDraw({
// Using the MapLibre Adapter from the separate package
adapter: new TerraDrawMapLibreGLAdapter({ map, lib }),
// Add the Rectangle Mode
modes: [new TerraDrawRectangleMode()],
});Putting these concepts together we can create a simple map with freehand drawing enabled like so:
<!doctype html>
<html>
<head>
<!-- Required Styles & Script -->
<link
rel="stylesheet"
href="https://unpkg.com/[email protected]/dist/maplibre-gl.css"
/>
<script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>
<script src="https://unpkg.com/[email protected]/dist/terra-draw.umd.js"></script>
</head>
<body>
<!-- Map Container (must have dimensions set!) -->
<div id="map" style="height:420px;"></div>
<script>
// Create MapLibre Map, targetting <div id="map">
// See https://maplibre.org/maplibre-gl-js/docs/
var map = new maplibregl.Map({
container: "map",
style: "https://demotiles.maplibre.org/style.json",
center: [-4.49049, 54.189649], // [lng, lat]
zoom: 5,
});
// Create Terra Draw
const draw = new terraDraw.TerraDraw({
adapter: new terraDraw.TerraDrawMapLibreGLAdapter({
map: map,
lib: maplibregl,
}),
modes: [new terraDraw.TerraDrawFreehandMode()],
});
// Start drawing
draw.start();
// Set the mode to rectangle
draw.setMode("freehand");
</script>
</body>
</html>You can find the full autogenerated API docs on the terra draw website.
There are a few other working examples that you can use as points of reference for creating a new app using Terra Draw:
- Development Example - showcases all of Terra Draw Modes and Adapters. It is meant for local development but can also be used as a guide of how to use Terra Draw with each Adapter without any framework.
- Terra Draw Website - Acts as a full working implementation of how to use Terra Draw. In this case it is used with popular framework Preact (has very similar API to React). It's Open Source too!
Guides