Drawing on the map

User interface elements that can be added to the map. The items in this section exist outside of the map's canvas element.

Marker

Creates a marker component

Extends Evented.
new Marker(options: Object?, legacyOptions: Options?)

Parameters

options(Object?)
NameDescription
options.element
HTMLElement?
DOM element to use as a marker. The default is a light blue, droplet-shaped SVG marker.
options.anchor
string
default: 'center'
A string indicating the part of the Marker that should be positioned closest to the coordinate set via Marker#setLngLat . Options are 'center' , 'top' , 'bottom' , 'left' , 'right' , 'top-left' , 'top-right' , 'bottom-left' , and 'bottom-right' .
options.offset
PointLike?
The offset in pixels as a PointLike object to apply relative to the element's center. Negatives indicate left and up.
options.color
string
default: '#F05123'
The color to use for the default marker if options.element is not provided. The default is light blue.
options.scale
number
default: 1
The scale to use for the default marker if options.element is not provided. The default scale corresponds to a height of 41px and a width of 27px .
options.draggable
boolean
default: false
A boolean indicating whether or not a marker is able to be dragged to a new position on the map.
options.clickTolerance
number
default: 0
The max number of pixels a user can shift the mouse pointer during a click on the marker for it to be considered a valid click (as opposed to a marker drag). The default is to inherit map's clickTolerance.
options.rotation
number
default: 0
The rotation angle of the marker in degrees, relative to its respective rotationAlignment setting. A positive value will rotate the marker clockwise.
options.pitchAlignment
string
default: 'auto'
map aligns the Marker to the plane of the map. viewport aligns the Marker to the plane of the viewport. auto automatically matches the value of rotationAlignment .
options.rotationAlignment
string
default: 'auto'
map aligns the Marker 's rotation relative to the map, maintaining a bearing as the map rotates. viewport aligns the Marker 's rotation relative to the viewport, agnostic to map rotations. auto is equivalent to viewport .
legacyOptions(Options?)

Example

const marker = new nmapsgl.Marker()
.setLngLat([30.5, 50.5])
.addTo(map);
// Set options
const marker = new nmapsgl.Marker({
color: "#FFFFFF",
draggable: true
}).setLngLat([30.5, 50.5])
.addTo(map);

Instance Members

Events

Custom Marker

Custom markers allow you to change the default NMaps GL markers to other icons or images.

Map initialization

To add custom markers, start by initializing the map with the desired options. An example code for this initialization is found below:

let map = new nmapsgl.Map({
container: 'map',
center: [-96, 37.8],
zoom: 3,
style: 'Streets'
});

Load GeoJSON data

The GeoJSON will be used to determine where markers will appear on the map. In the case of markers, the GeoJson data geometry type must be Point. Below is a code example where Geoson data is declared inline and stored in the variable geojson:

let geojson = {
type: 'FeatureCollection',
features: [
{
type: 'Feature',
geometry: {
type: 'Point',
coordinates: [-77.032, 38.913]
}
},
{
type: 'Feature',
geometry: {
type: 'Point',
coordinates: [-122.414, 37.776]
}
}
]
};

Add markers to the map

Once the data has been loaded, the HTML elements for each marker must be created and linked to the GeoJSON features using the Marker method. This can be done, for example, as follows:

// add markers to map
geojson.features.forEach((marker) => {
// create a HTML element for each feature
let el = document.createElement('div');
el.className = 'marker';
// make a marker for each feature and add to the map
new nmapsgl.Marker(el)
.setLngLat(marker.geometry.coordinates)
.addTo(map);
});

To customize the marker, add CSS to specify its style. In the previous example, a classname marker was created and associated to the Marker HTML element.
Below, there's an example of marker customization where its icon and style is changed (it's assumed that there's a image "custom-icon.png" in the project):

.marker {
background-image: url('custom_marker.png');
background-size: cover;
width: 50px;
height: 50px;
border-radius: 50%;
cursor: pointer;
}

The final result of a map with custom markers is as follows:

A popup component.

Extends Evented.
new Popup(options: Object?)
options(Object?)
NameDescription
options.closeButton
boolean
default: true
If true , a close button will appear in the top right corner of the popup.
options.closeOnClick
boolean
default: true
If true , the popup will closed when the map is clicked.
options.closeOnMove
boolean
default: false
If true , the popup will closed when the map moves.
options.focusAfterOpen
boolean
default: true
If true , the popup will try to focus the first focusable element inside the popup.
options.anchor
string?
A string indicating the part of the Popup that should be positioned closest to the coordinate set via Popup#setLngLat . Options are 'center' , 'top' , 'bottom' , 'left' , 'right' , 'top-left' , 'top-right' , 'bottom-left' , and 'bottom-right' . If unset the anchor will be dynamically set to ensure the popup falls within the map container with a preference for 'bottom' .
options.offset
(number | PointLike | Object)?
A pixel offset applied to the popup's location specified as:
  • a single number specifying a distance from the popup's location
  • a PointLike specifying a constant offset
  • an object of Points specifing an offset for each anchor position Negative offsets indicate left and up.
options.className
string?
Space-separated CSS class names to add to popup container
options.maxWidth
string
default: '240px'
A string that sets the CSS property of the popup's maximum width, eg '300px' . To ensure the popup resizes to fit its content, set this property to 'none' . Available values can be found here: https://developer.mozilla.org/en-US/docs/Web/CSS/max-width
const markerHeight = 50, markerRadius = 10, linearOffset = 25;
const popupOffsets = {
'top': [0, 0],
'top-left': [0,0],
'top-right': [0,0],
'bottom': [0, -markerHeight],
'bottom-left': [linearOffset, (markerHeight - markerRadius + linearOffset) * -1],
'bottom-right': [-linearOffset, (markerHeight - markerRadius + linearOffset) * -1],
'left': [markerRadius, (markerHeight - markerRadius) * -1],
'right': [-markerRadius, (markerHeight - markerRadius) * -1]
};
const popup = new nmapsgl.Popup({offset: popupOffsets, className: 'my-class'})
.setLngLat(e.lngLat)
.setHTML("<h1>Hello World!</h1>")
.setMaxWidth("300px")
.addTo(map);

Shapes

Various shapes can be added to the map. A shape is an object on the map, tied to a latitude/longitude coordinate. The following shapes are available: polylines, polygons, rectangles and circles.

Polyline

Creates a polyline component.

new Polyline(options: Object?)

Parameters

options(Object?)
NameDescription
options.strokeColor
string?
The color with which the line will be drawn. The default is black (#000000).
options.strokeOpacity
number?
Specifies a numerical value between 0.0 and 1.0 to determine the opacity of the line color. The default is 1.0.
options.strokeWeight
number?
The width of the line in pixels. The default is 3.

Example

const coordinates = [
[-122.483696, 37.833818],
[-122.483482, 37.833174],
[-122.483396, 37.8327]
];
let polyline = new nmapsgl.Polyline()
.setPath(coordinates)
.addTo(map);
// Set options
let polyline = new nmapsgl.Polyline({
strokeColor: '#888',
strokeWeight: 8
}).setPath(coordinates)
.addTo(map);// add the polyline to the map

Instance Members

Polygon

Creates a polygon component.

new Polygon(options: Object?)

Parameters

options(Object?)
NameDescription
options.strokeColor
string?
The color used for the polygon outline. The default is black (#000000).
options.strokeOpacity
number?
Specifies a numerical value between 0.0 and 1.0 to determine the opacity of the outline's color. The default is 1.0.
options.strokeWeight
number?
The width of the outline in pixels. The default is 3.
options.fillColor
string?
The color used to fill the polygon area. The default is black (#000000).
options.fillOpacity
number?
Specifies a numerical value between 0.0 and 1.0 to determine the opacity of the polygon's color area. The default is 0.5.

Example

const coordinates = [
[-67.13734, 45.13745],
[-70.11617, 43.68405],
[-70.98176, 43.36789],
[-70.30495, 45.91479],
[-68.2343, 47.35462],
[-67.13734, 45.13745]
];
let polygon = new nmapsgl.Polygon()
.setPath(coordinates)
.addTo(map);
// Set options
let polygon = new nmapsgl.Polygon({
strokeColor: "#FF0000",
strokeOpacity: 0.8,
strokeWeight: 2,
fillColor: "#FF0000",
fillOpacity: 0.35,
}).setPath(coordinates)
.addTo(map);

Instance Members

Rectangle

Creates a rectangle component.

new Rectangle(options: Object?)

Parameters

options(Object?)
NameDescription
options.strokeColor
string?
The color used for the rectangle outline. The default is black (#000000).
options.strokeOpacity
number?
Specifies a numerical value between 0.0 and 1.0 to determine the opacity of the outline's color. The default is 1.0.
options.strokeWeight
number?
The width of the outline in pixels. The default is 3.
options.fillColor
string?
The color used to fill the rectangle area. The default is black (#000000).
options.fillOpacity
number?
Specifies a numerical value between 0.0 and 1.0 to determine the opacity of the rectangle's color area. The default is 0.5.

Example

const bounds = {
north: 33.685,
south: 33.671,
east: -116.234,
west: -116.251,
};
let rectangle = new nmapsgl.Rectangle()
.setBounds(bounds)
.addTo(map);
// Set options
let rectangle = new nmapsgl.Rectangle({
strokeColor: "#FF0000",
strokeOpacity: 0.8,
strokeWeight: 2,
fillColor: "#FF0000",
fillOpacity: 0.35,
}).setBounds(bounds)
.addTo(map);

Instance Members

Circle

Creates a circle component.

new Circle(options: Object?)

Parameters

options(Object?)
NameDescription
options.radius
number?
Defines the circle radius in pixels. The default is 5.
options.strokeColor
string?
The color used for the circle outline. The default is black (#000000).
options.strokeOpacity
number?
Specifies a numerical value between 0.0 and 1.0 to determine the opacity of the outline's color. The default is 1.0.
options.strokeWeight
number?
The width of the outline in pixels. The default is 3.
options.fillColor
string?
The color used to fill the circle area. The default is black (#000000).
options.fillOpacity
number?
Specifies a numerical value between 0.0 and 1.0 to determine the opacity of the circle's color area. The default is 0.5.

Example

const center = [-116.243, 33.678];
let circle = new nmapsgl.Circle()
.setCenter(center)
.addTo(map);
// Set options
let circle = new nmapsgl.Circle({
strokeColor: "#FF0000",
strokeOpacity: 0.8,
strokeWeight: 2,
fillColor: "#FF0000",
fillOpacity: 0.35,
radius: 10
}).setCenter(center)
.addTo(map);

Instance Members

Ruler

A RulerControl provides a button to add points to the map and calculate the distance between them.

new RulerControl(options: Object?)

Parameters

options(Object?)
NameDescription
options.unit
string
default: Metric
Distance unit: Metric or Imperial.

Example

map.addControl(new nmapsgl.RulerControl({
unit: 'Imperial'
}));