Skip to main content

Featuresets

SDK SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 3.9.0>= 11.9.0>= 11.9.0

A style's featuresets property defines groups of style layers that are available for interaction when the style is imported from another style. Our mapping libraries and SDKs allow you add interactions such as click, and hover to featuresets, and quickly access the underlying feature data for use in your application or to set feature states for dynamic styling.

When using an imported style, its layers are not accessible at runtime. Featuresets exist to allow style designers to expose a subset of layers for interaction. You can think of featuresets as a way of defining an API for the imported style.

In the example below the style defines featureset poi that combines poi-label and transition-label layers.

{
"featuresets": {
"poi": {
"selectors": [
{
"layer": "poi-label",
"properties": { // Defines which properties are available to user of POI featuerset
"name": ["get", "name"],
"group": "poi"
}
},
{
"layer": "transit-label",
"properties": {
"name": ["get", "stop_name"],
"group": "transit"
},
"featureNamespace": "poi-B"
}
]
}
},
"layers": [
{"id": "poi-label", ...}
{"id": "transit-label", ...}
]
}

Featuresets also define the feature properties to expose during map interactions. Each selector includes a properties object to identify the available properties. The properties can be accessed in the interaction handler (see the Add and interaction to a featureset code snippet below).

A common pattern when adding featuresets to a style is to define useful feature states into the layers exposed via featuresets. For example, the style designer could define a highlight feature state which can be used to change a feature's color when it is interacted with. The following snippet shows how to define a highlight feature state in the poi-label layer.

{
"id": "poi-label",
"paint": {
// Highlight the label when feature state is set.
// Note: this is just an example, and may not work as expected in practice.
// The actual implementation may require additional logic to handle different states.
"text-color": ["case", ["boolean", ["feature-state", "highlight"], false], "#f00", "#000"]
}
}

Our mapping libraries and SDKs include similar APIs for interacting with featuresets. The following code snippets show how to add a click interaction to notional poi featureset defined above on various platforms.

Add an interaction to featureset
// Add a click interaction to `poi` featureset defined in the style imported with `my-poi-fragment` id.
map.addInteraction('poi-click-interaction', {
type: 'click',
target: {featuresetId: 'poi', importId: 'my-poi-fragment'},
handler: (e) => {
// The properties defined in the selectors `properties` objects.
console.log("Poi clicked", e.feature.properties.name, e.feature.properties.group)
map.setFeatureState(e.feature, {highlight: true});
}
});
Note

The Mapbox Standard and Mapbox Standard Satellite styles define featuresets that can be used to interact with the layers in the style. For example, the Mapbox Standard style defines a poi featureset that can be used to interact with the POI layers in the style.

Featureset

A featureset defines a named group of layers that are available for interaction when the style is imported from another style.

metadata

EXPERIMENTAL
Optional .

Arbitrary properties useful to track with the stylesheet, but do not influence rendering. Properties should be prefixed to avoid collisions, like 'mapbox:'.

selectors

EXPERIMENTAL
Optional array of selector .

A collection of categorized selectors.

Selector

A selector describes a layer from the current style and the properties from its features that will be available for interactions.

layer

EXPERIMENTAL
Required string .

The ID of a layer that exists in the current style.

featureNamespace

EXPERIMENTAL
Optional string .

An optional field that represents the feature namespace defined by the selector within a featureset to which this feature belongs. If the underlying source is the same for multiple selectors within a featureset, the same featureNamespace should be used across those selectors.

properties

EXPERIMENTAL
Optional selectorProperty .

Properties accessible to the end user through queried feautures. If properties are empty, no feature properties are exposed. If undefined, all original feature properties will be accessible.

SelectorProperty

*

EXPERIMENTAL
Optional .

The value of the property. It can be an expression that generates the returned value from the feature, or a constant value specifying the returned value.

Was this page helpful?