Marker Layout API reference
This reference documents every object and method available. Each section describes classes or objects as well as their properties, parameters, methods, and associated events. Many sections also include inline code examples and related resources.
The MarkerLayout is a helper to create non-colliding marker overlays on top of MapTiler SDK. Fed by a vector layer from a tileset or a GeoJSON source, it can be tuned with plenty of options. Thanks to its non-opinionated and logic-only approach, it lets you bind any kind of rendering you wish for your markers: vanilla HTML div, React components, floating canvas, etc. as it computes the position and size of the markers but lets you handle the rendering part.
Example (create a Marker Layout with some not default options)
Constructor
Creates a Marker Layout component
Parameters
| options.layers
default: uses all the layers available
|
IDs of layers to query for vector features. |
|---|---|
| options.markerSize
default:
[150, 50] |
Size of the markers on screen space [width, height]. |
| options.max
default: no maximum
|
Maximum number of markers to keep. |
| options.markerAnchor
default:
"center" |
Position of the marker relative to its anchor point. |
| options.offset
default:
[0, 0] |
Offset to apply to the marker, in number of pixel, relative to its anchor position. First element of the array is the horizontal offset where negative shifts towards the left and positive shifts towards the right. Second element of the array is the vertical offset where negative shifts towards the top and positive shifts towards the bottom. |
options.filter
(feature: MapGeoJSONFeature) => voiddefault: none
|
A filter function can be provided. Each feature will be tested against this filter function,
and the returned value can be true (the feature is kept) or
false (the feature is discarded).
|
options.sortingProperty
(feature: MapGeoJSONFeature) => number |
string?
default: none
|
Property to sort the features by. If not provided, the features will not be sorted. Alternatively, the sorting property can be a function that takes the feature as argument and returns a number, aka. the sorting value (or rank) |
options.sortingOrder
"ascending" |
"descending"?
default:
"ascending" |
Sorting order, only relevant if the option .sortingProperty is provided, or else will be ignored.
|
| options.groupBy
default: no grouping
|
Property to group by. The property must be present in the properties
object of the feature unless the value of groupBy is equal to
"coordinates", then the geometry coordinates are
being used.
|
| options.maxNbFeaturesPerMarker
default:
Infinity |
Markers can contain multiple features, this parameter can be set to have a strict limit. |
| options.maxRatioUnitSize
default:
2.5 |
When a marker contains multiple features, its size can get bigger. This number is the max ratio applied to the
defined markerSize. Intentionally non-integer so that the user can see there is still half an element to
show at the bottom and understand they can scroll for more.
|
Methods
As we interact with the map (pan, zoom, rotation, etc.) we need to know which markers are now visible, disappeared outside the viewport or are still visible but at a different (screen space) location.
To compute this, a MarkerLayout instance has two methods:
Compute a complete new status of markers, returning a MarkerStatus.
In case many vector features are found in the specified layers with
the provided filter, this may have an impact on performances and
may not be suitable to call from a map.on("move", () => { ... }) event.
Only update a single AbstractMarker with a new screen space position.
This is convenient to use when there are hundreds of vector features found but we only want to update
the position, say, of the ones retrieved with the previous full .update()
call. In this performance-wise conservative mode, one would typically bind .update()
to the Map event "idle" and bind
.softUpdateAbstractMarker(am) to the Map
event "move".
AbstractMarker)
: The single AbstractMarker to update
Reset the internal MarkerStatus if we need to restart
from a blank slate without creating a new MarkerLayout instance.