queryRenderedFeatures — MapLibre GL JS API reference

queryRenderedFeatures()

queryRenderedFeatures(geometryOrOptions?: QueryRenderedFeaturesOptions | PointLike | [PointLike, PointLike], options?: QueryRenderedFeaturesOptions): MapGeoJSONFeature[]

Defined in: ui/map.ts:2608

Returns an array of MapGeoJSONFeature objects representing visible features that satisfy the query parameters.

Parameters

Parameter	Type	Description
`geometryOrOptions?`	`QueryRenderedFeaturesOptions` \| `PointLike` \| [`PointLike`, `PointLike`]	(optional) The geometry of the query region in pixel points within the map viewport: either a single pixel point or a pair of top-left and bottom-right pixel points describing a bounding box. The origin of the pixel points is at the top-left of the map viewport. Omitting this parameter (i.e. calling Map.queryRenderedFeatures with zero arguments, or with only a `options` argument) is equivalent to passing a bounding box encompassing the entire map viewport. The geometryOrOptions can receive a QueryRenderedFeaturesOptions only to support a situation where the function receives only one parameter which is the options parameter.
`options?`	`QueryRenderedFeaturesOptions`	(optional) Options object.

Returns

MapGeoJSONFeature[]

An array of MapGeoJSONFeature objects.

The properties value of each returned feature object contains the properties of its source feature. For GeoJSON sources, only string and numeric property values are supported (i.e. null, Array, and Object values are not supported).

Each feature includes top-level layer, source, and sourceLayer properties. The layer property is an object representing the style layer to which the feature belongs. Layout and paint properties in this object contain values which are fully evaluated for the given zoom level and feature.

Only features that are currently rendered are included. Some features will not be included, like:

Features from layers whose visibility property is "none".
Features from layers whose zoom range excludes the current zoom level.
Symbol features that have been hidden due to text or icon collision.

Features from all other layers are included, including features that may have no visible contribution to the rendered result; for example, because the layer's opacity or color alpha component is set to 0.

The topmost rendered feature appears first in the returned array, and subsequent features are sorted by descending z-order. Features that are rendered multiple times (due to wrapping across the antemeridian at low zoom levels) are returned only once (though subject to the following caveat).

Because features come from tiled vector data or GeoJSON data that is converted to tiles internally, feature geometries may be split or duplicated across tile boundaries and, as a result, features may appear multiple times in query results. For example, suppose there is a highway running through the bounding rectangle of a query. The results of the query will be those parts of the highway that lie within the map tiles covering the bounding rectangle, even if the highway extends into other tiles, and the portion of the highway within each map tile will be returned as a separate feature. Similarly, a point feature near a tile boundary may appear in multiple tiles due to tile buffering.

Examples

Find all features at a point

let features = map.queryRenderedFeatures(
  [20, 35],
  { layers: ['my-layer-name'] }
);

Find all features within a static bounding box

let features = map.queryRenderedFeatures(
  [[10, 20], [30, 50]],
  { layers: ['my-layer-name'] }
);

Find all features within a bounding box around a point

let width = 10;
let height = 20;
let features = map.queryRenderedFeatures([
  [point.x - width / 2, point.y - height / 2],
  [point.x + width / 2, point.y + height / 2]
], { layers: ['my-layer-name'] });

Query all rendered features from a single layer

let features = map.queryRenderedFeatures({ layers: ['my-layer-name'] });

See

Get features under the mouse pointer