[Feature Request] Control layer and feature ordering in MapLibre/Mapbox

[jiacona]

First of all, thanks so much for all your work on this library. I've been using it quite heavily at the moment and it has been working great.

Is your feature request related to a problem? Please describe.

I'm using TerraDraw as part of a map based site layout app and needed to be able to control layer and feature ordering.

I need to order different objects that can be added to the map as well as lines and polygons drawn by TerraDraw. In my scenario, I needed polygons to come first, then lines, then our other layers, regardless of when they are drawn.

Within the TerraDraw polygon layer, I am using functional styling to be able to draw different types of polygons. These polygon types also needed to be drawn in a deterministic order.

Describe your proposed idea for the solution to this problem

I am using MapLibre, so the proposed solution only applies to that adapter.

Layer ordering

Deterministic layer order can be achieved by using the beforeId param to anchor a layer in relative order to another known layer. Exposing this parameter as a mode style would enable controlling where in the layer hierarchy objects are drawn.

Feature ordering

Within a layer, features can be ordered by supplying a sortKey as a functional mode style parameter. The same criteria used to determine different feature styling can be used to set a sortKey.

Additional context

I am currently using a forked version of TerraDraw where I exposed both beforeId and sortKey. You can have a look at my minimal implementation here 60aecdb. If this type of feature is something you think could be more generally useful I'd be happy to put in some time to make it PRable.

[JamesLMilner]

@jiacona firstly, thanks for the kind words, I appreciate the sentiment and to hear you have been enjoying using Terra Draw!

These are both interesting ideas and can totally see why they would be valuable! They actually partially remind me of an older issue, #63, which was just specifically about keeping Terra Draw layers on top. However making this more configurable might be a nicer longer term goal.

At the moment I am about 80% of the way to just releasing a version 1 of Terra Draw which uses separate modules for the adapters, so TerraDrawMapLibreGLAdapter will be in it's own package. One of the nice things (at least I think!) with Terra Draw w designed so that you can create your own adapters with custom requirements fairly easily. However I can see why features like this would be useful for a wider audience. After I have got version 1 out, I will think a bit more about this and if/how the best way to make it a reality.

One last thing, mostly for my own curiosity, what are you working on? :)

[jiacona]

Interesting, #63 would have actually given me the opposite behaviour of what I need, which is why making it configurable seems valuable!

I did think about trying to build a custom adapter/mode, but would have had to customise 3 different things (Mapbox adapter, Polygon, and Select modes). It seemed like I would need to copy most of the behaviour out of the existing ones to make that work.

I'm working on https://www.blocktype.co.uk

[JamesLMilner]

@jiacona just to follow up here, I don't think I fully appreciated what you were saying the first time around about the sortKey piece. Terra Draw already has a similar concept called zIndex which we use properly in other adapters, but not in the MapLibre or Mapbox Adapters. I am just raising a PR to use the moveLayer with the beforeId but later on I want to make use of the zIndex to control the layer ordering properly.

Thanks again for your input! I wish I could move faster on this.

[jiacona]

Thanks for the update @JamesLMilner. I did notice that there was a zIndex property in other adapters. Mapbox/maplibre don't really seem to have the concept of zIndex though so I'm curious as to how you might go about making that an option.

If you have any questions about what I'm trying to achieve with the sortKey just let me know and I'll see if I can clarify.

[JamesLMilner]

Didn't mean to mark this as complete, reopening

[jo-chemla]

According to the PR linked, renderBelowLayerId introduced in 1.1.0 (2025-05-06) can be passed to the constructor as config for the mapbox/maplibre-adapters.

Looking at the mapbox-gl-js api movelayer doc and terradraw renderBelowLayerId implementation, this property is therefore useful to ensure the terradraw layers appear beneath a given layer id.

// Move a layer with ID 'polygon' before the layer with ID 'country-label'. The polygon layer will appear beneath the country-label layer on the map.
map.moveLayer('polygon', 'country-label');

terra-draw/packages/terra-draw-maplibre-gl-adapter/src/terra-draw-maplibre-gl-adapter.ts

Lines 472 to 477 in 76af791

	if (this._renderBeforeLayerId) {
	this._map.moveLayer(pointId, this._renderBeforeLayerId);
	this._map.moveLayer(lineStringId, pointId);
	this._map.moveLayer(polygonStringId + "-outline", lineStringId);
	this._map.moveLayer(polygonStringId, lineStringId);
	}

Could we introduce a similar feature config/param renderAboveLayerId that would just invert the first line to something like this._map.moveLayer(renderAboveLayerId, pointId);? Should I submit a PR or do you want to handle this another way? I saw zIndex being mentioned around the repo, but I understand this would serve a different purpose. Note this would be especially useful when user loads a new background basemap source/layer - eg switching from bing satellite to google hybrid TMS sources while having the terra-draw vector editing layers still appear on-top.

Edit: just made the suggested PR here: #615

[JamesLMilner]

Hey @jo-chemla - thanks for the input. I actually was playing with this idea when we implemented it but decided that you should be able to move the layer to the appropriate place renderBelowLayerId. Is there a reason renderBelowLayerId doesn't allow you to position this correctly in the layer stack? If you have the list of layers you should be able to position in anywhere in the list, as examples:

renderBelowLayerId: 1

Layer 1
Terra Draw Layers
Layer 2
Layer 3

renderBelowLayerId: 3

Layer 1
Layer 2
Layer 3
Terra Draw Layers

The default scenario if you don't use renderBelowLayerId:

Terra Draw Layers
Layer 1
Layer 2
Layer 3