Annotations

Annotations allow you to add interactive elements at specific geographic coordinates on your map. This guide explains how to create and customise annotations with MapLayr.

Creating an Annotation Layer

Annotations are added to an AnnotationLayer, which must be created and added to your map view:

// Create an annotation layer
const layer = new maplayr.AnnotationLayer();

// Add the layer to your map view
mapView.addLayer(layer);
Copy

Adding Annotations

Annotations consist of:

1. A geographic coordinate position
2. A factory function that generates a DOM element

Here's an example of how to create annotations for points of interest:

const pointsOfInterest = [
  {
    "name": "Shipwreck Restaurant",
    "location": new maplayr.Coordinates(36.69427, -6.41905)
  },
  {
    "name": "Mystical Waters",
    "location": new maplayr.Coordinates(36.69035, -6.40912)
  },
  {
    "name": "Underwater Kingdom",
    "location": new maplayr.Coordinates(36.69878, -6.41632)
  }
];

for (const poi of pointsOfInterest) {
  const annotation = new maplayr.Annotation({
    position: poi.location,
    node() {
      const container = document.createElement("div");
      container.className = "annotation";
      container.textContent = poi.name;
      
      return container;
    }
  });
  
  // Add the annotation to the layer
  layer.add(annotation);
}
Copy

Styling Annotations

Annotations can be styled with CSS. Here's an example:

.annotation {
  padding: 2px 8px;
  border-radius: 8px;
  box-shadow: 0 2px 4px rgb(0 0 0 / 0.5);
  background-color: rgb(43 96 166);
  font-family: sans-serif;
  color: white;
}
Copy

Positioning Annotations

By default, annotations are centred on their geographic coordinates. You can adjust this with two properties:

Anchor

The anchor property defines the relative position of the annotation's anchor point from its top-left corner:

const annotation = new maplayr.Annotation({
  position: coordinates,
  anchor: { x: 0.5, y: 1.0 }, // Bottom centre
  node() { /* ... */ }
});
Copy

Value	Description
{ x: 0, y: 0 }	Top-left corner
{ x: 0.5, y: 0.5 }	Centre (default)
{ x: 1, y: 1 }	Bottom-right corner

Anchor Offset

The anchorOffset property adds an additional offset in CSS pixels:

const annotation = new maplayr.Annotation({
  position: coordinates,
  anchorOffset: { x: 0, y: -10 }, // 10px up from the anchor point
  node() { /* ... */ }
});
Copy

Dynamic Annotations

Annotations can contain any DOM elements and can be updated or animated in response to state changes or user interactions.