Featuresets
SDK Support | Mapbox GL JS | Android SDK | iOS 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 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});
}
});
// Add a click interaction to `poi` featureset defined in the style imported with `my-poi-fragment` id.
mapboxMap.addInteraction(
ClickInteraction.featureset(id = "poi", importId = "my-poi-fragment") { feature, context ->
val name = feature.properties.getString("name")
val group = feature.properties.getString("group")
// Log the clicked POI information
println("Poi clicked: $name, $group")
// Highlight the clicked feature
mapboxMap.setFeatureState(
featuresetFeature = feature,
state = mapOf("highlight" to true)
)
true // Stops propagation
}
)
// Add a click interaction to `poi` featureset defined in the style imported with `my-poi-fragment` id.
mapView.mapboxMap.addInteraction(TapInteraction(.featureset("poi", importId: "my-poi-fragment")) { [weak mapView] feature, context in
if let name = feature.properties["name"] as? String,
let group = feature.properties["group"] as? String {
print("Poi clicked: \(name), \(group)")
}
// Highlight the clicked feature
mapView?.mapboxMap.setFeatureState(feature, state: ["highlight": true])
return true // Stops propagation
})
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
Arbitrary properties useful to track with the stylesheet, but do not influence rendering. Properties should be prefixed to avoid collisions, like 'mapbox:'.
selectors
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
The ID of a layer that exists in the current style.
featureNamespace
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
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
*
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.