GeoJSONVectorTileLayer

GeoJSONVectorTileLayer is a vector tile layer for rendering GeoJSON data on the map.

The layer is based on the open-source geojson-vt library. It slices the GeoJSON data into tiles in a worker in real time and returns the result to the main thread for rendering.

Advantages of loading GeoJSON data with the vector tile mechanism:

• High performance: easily parses and renders GeoJSON files of hundreds of megabytes
• Good experience: all data processing runs in the worker and does not block the main thread

It is a subclass of VectorTileLayer and inherits the methods and options of VectorTileLayer.

Likewise, styles written for VectorTileLayer can be applied to GeoJSONVectorTileLayer without modification, unifying server-side vector tile data and local GeoJSON data.

NOTE

A * on a parameter or option name means the parameter or option is required. For example, the * after id below means the parameter id is required:

• id* String the layer id

Style

Vector tiles support styles for vector features (points, lines and polygons), and also have the ability to build lines and polygons into 3D lines and 3D faces and render them with 3D PBR materials.

Vector tiles integrate feature-filter and function-type to support data filtering and dynamic styling, making it easy to categorize the data in vector tiles and render them with different styles, levels and material magic for stunning effects.

Vector tiles are therefore well suited to categorized data rendering in large scenes, such as city building clusters. Compared with static data like 3dtiles, vector tiles benefit from a better ecosystem and the separation of style and data, which eliminates data update costs while providing styling capabilities that are hard to achieve with 3dtiles.

The vector tile style adopts a plugin-based design: styles are defined by render plugins. For the details of the render plugins, refer to the style manual. Here is a simple style example:

Style Example

{
  "style": [
    {
      "renderPlugin": {
        "type": "fill",
        "dataConfig": {
          "type": "fill",
          "only2D": true
        },
        "sceneConfig": {
          "depthFunc": "always",
          "blendSrc": "one"
        }
      },
      "symbol": {
        "visible": true,
        "polygonFill": "rgba(0,0,0,1)",
        "polygonOpacity": 1
      },
      "filter": {
        "title": "desert",
        "value": [
          "all",
          [
            "==",
            "$layer",
            "desert"
          ],
          [
            "==",
            "$type",
            "Polygon"
          ]
        ]
      }
    },
    {
      "renderPlugin": {
        "type": "line",
        "dataConfig": {
          "type": "line",
          "only2D": true
        },
        "sceneConfig": {
          "blendSrc": "one"
        }
      },
      "symbol": {
        "visible": true,
        "lineOpacity": 1,
        "lineWidth": 1,
        "lineColor": "rgba(0,0,0,1)",
        "lineJoin": "miter",
        "lineCap": "butt",
        "lineDx": 0,
        "lineDy": 0,
        "lineDasharray": [
          0,
          0,
          0,
          0
        ],
        "lineDashColor": "rgba(0,0,0,1)",
        "lineStrokeWidth": 0,
        "lineStrokeColor": "rgba(0,0,0,1)"
      },
      "detail": {
        "layer": "desert-outline",
        "enable": {
          "lineWidth": false,
          "lineColor": false,
          "lineStrokeWidth": false,
          "lineStrokeColor": false
        }
      },
      "filter": {
        "title": "desert-outline",
        "value": [
          "all",
          [
            "==",
            "$layer",
            "desert"
          ],
          [
            "==",
            "$type",
            "Polygon"
          ]
        ]
      }
    }
  ]
}

Constructor

import { GeoJSONVectorTileLayer } from '@maptalks/gl-layers';

new GeoJSONVectorTileLayer('geojson0', {
  data: 'path/to/example.geojson'
});

Details

Parameters:

• id* String the layer id
• options* Object options, the available options are as follows:

Option	Type	Description	Default
data*	Object/String	A GeoJSON data object or a URL	null
features	Boolean	Whether tiles return feature data; for a GeoJSON layer, only the feature id is returned	true
tileBuffer	Number	The tile buffer size	64
extent	Number	The tile coordinate extent (the encoding precision of geometries)	8192
simplifyTolerance	Number	The tile simplification tolerance (a larger value means more simplification)	3
generateOMBB	Boolean	Whether to generate the oriented minimum bounding box (OMBB, to speed up picking)	true
convertFn	String	The data conversion function string (executed as convert(data) in the worker)	null
fetchOptions	Object	fetch options	null
style	Object	The style object of the layer	null
subdomains	String[]	subdomains, used to replace {s} in the URL template	null
tileSize	Number[]	The tile width and height, in pixels	[512, 512]
offset	Number[]/Function	The tile offset in pixels. A two-element array or a function; the function takes zoom (the tile zoom level) as its argument, offset(zoom) {}	[0, 0]
features	Boolean	Whether tiles return feature data	true
schema	Boolean	Whether tiles return the attribute schema of the data	false
collision	Boolean	Whether to enable collision detection for points and text	true
picking	Boolean	Whether the layer is allowed to query data with the identify or identifyAtPoint methods	true
pickingPoint	Boolean	Whether the query results of identify or identifyAtPoint include the 3D spatial coordinates of the query point	true
pickingGeometry	Boolean	Whether the query results of identify or identifyAtPoint include Geometry	false
iconErrorUrl	String	The fallback image URL for failed icon requests	null
collisionFrameLimit	Number	The time limit for collision computation per frame, in ms	1.5
defaultRendering	Boolean	Whether to enable default style rendering when there is no style	true
textGamma	Number	The gamma value of text, which can be used to adjust text sharpness	1
maxIconSize	Number	The maximum icon size limit	254
styleScale	Number	The overall scale factor of the layer's icons and text	1
spatialReference	String / Object	The spatial reference of the layer	"preset-vt-3857"
tileSystem	Number[]	A four-element array describing the TileSystem. The TileSystem defines the origin coordinate of tiles and the numbering rule on the X/Y axes. See this link for details	null
maxAvailableZoom	Number	The maximum available zoom level. When the map zoom level exceeds maxAvailableZoom, tiles of the maxAvailableZoom level are displayed.	null
repeatWorld	Boolean	Whether to repeat the world when the whole world does not fill the screen at low zoom levels	true
crossOrigin	String	The cross origin setting of the tile data	null
debug	Boolean	Whether to enable debug info; when enabled, tile indices and extents are drawn on the map	false
maxCacheSize	Number	The maximum number of cached tiles	256
zoomOffset	Number	The offset between the tile zoom level and the map zoom level	0
errorUrl	String	The fallback URL for failed tile requests	null
token	String	Used to replace {token} in the URL template, e.g. http://foo/bar/{z}/{x}/{y}?token={token}	null

|attribution | String | The attribution of the layer | null | |minZoom | Number | The minimum zoom level at which the layer is displayed | null | |maxZoom | Number | The maximum zoom level at which the layer is displayed | null | |visible | Boolean | Whether the layer is visible | true | |opacity | Number | The opacity of the layer | 1 | |hitDetect | Boolean | Whether to enable layer drawing detection (dynamic mouse cursor styles); disabling it can improve performance | true | |collisionScope | String | The scope of the collision detection index: "map" or "layer" | "layer" |

Methods

getData()

Gets the GeoJSON data.

const layer = new GeoJSONVectorTileLayer('vt0', {
  data: 'path/to/example.geojson'
});
const data = layer.getData();

Returns:

• String | Object

setData(data)

Updates the layer data.

const layer = new GeoJSONVectorTileLayer('vt0', {
  data: 'path/to/example.geojson'
});
layer.setData('path/to/another.geojson');

Parameters:

• data String | Object GeoJSON data or a remote URL of the data.

Returns:

• this

getExtent()

Gets the extent of the GeoJSON data.

const layer = new GeoJSONVectorTileLayer('vt0', {
  data: 'path/to/example.geojson'
});
const extent = layer.getExtent();

Returns:

• maptalks.Extent

getFeature(id)

Gets the feature with the given id.

const layer = new GeoJSONVectorTileLayer('vt0', {
  data: 'path/to/example.geojson'
});
const feature = layer.getFeature(id);

Returns:

• Object

getGeometryById(id)

Gets the feature by id (an alias of getFeature).

const layer = new GeoJSONVectorTileLayer('vt0', {
  data: 'path/to/example.geojson'
});
const feature = layer.getGeometryById(id);

Parameters:

• id Number | String the feature id

Returns:

• Object

Methods Inherited from VectorTileLayer

setStyle(layerStyle)

Sets the style of the layer. See this link for the style documentation.

const style = {
  style: [
    {
      filter : true,            // 数据的过滤条件
      renderPlugin: {           // 渲染插件
        type : 'native-point',
        dataConfig : {
          type : 'native-point'
        }
      },
      symbol: {                 // 样式定义
        markerSize: 6,
        markerType: 'circle',
        markerFill: '#0f0'
      }
    }
  ]
};
layer.setStyle(style);

Parameters:

• style Object the layer style object, with the following optional properties:

Property	Type	Description	Default
style	Object[]	The render plugin array	[]
featureStyle	Object[]	The render plugin list of a single feature	[]
$root	String	The root path of the resource directory	null

Returns:

• this

getStyle()

Gets the layer style.

Returns:

• Object

getComputedStyle()

Gets the processed layer style. The main differences from style are:

• If $root is defined in the style, all resource paths in computedStyle are the merged paths
• The style definitions in style may be compressed, while those in computedStyle are uncompressed

Returns:

• Object

outlineAll()

Highlights all data on the layer.

Because highlighting is implemented with post-processing, the layer must be added to a GroupGLLayer with the outline post-processing enabled.

layer.addTo(groupGLLayer);
layer.outlineAll();

Returns:

• this

outlineBatch(idx)

Highlights the data rendered by the render plugin with index idx in the style.

Same as outlineAll: the layer must be added to a GroupGLLayer with the outline post-processing enabled.

layer.addTo(groupGLLayer);
layer.outlineBatch(0);

Parameters:

• idx Number the index in the style

Returns:

• this

outline(idx, featureIds)

Highlights the specified features among the data rendered by the render plugin with index idx.

layer.addTo(groupGLLayer);
layer.outline(0, [0]);

Parameters:

• idx Number the index in the style
• featureIds Number[] | String[] an array of feature ids

Returns:

• this

cancelOutline()

Cancels the highlight.

Returns:

• this

updateSymbol(idx, symbol)

Updates the symbol of the render plugin with index idx.

layer.updateSymbol(0, { polygonFill: '#0f0' });

Parameters:

• idx Number the render plugin index
• symbol Object the symbol properties to update

Returns:

• this

updateFeatureSymbol(idx, styleIdx, symbol)

Updates the symbol of the render plugin with index styleIdx in the feature style with index idx.

const style = {
  featureStyle: [
    {
      id: 16,
      style: [
        {
          renderPlugin: {
            dataConfig: {
              type: 'fill'
            },
            sceneConfig: {
              antialias: false
            },
            type: 'fill'
          },
          symbol: {
            polygonFill: '#f00'
          }
        }
      ]
    }
  ]
}
layer.updateFeatureSymbol(0, 0, { polygonFill: '#0f0' });

Parameters:

• idx Number the index of the feature style in featureStyle
• styleIdx Number the style index
• symbol Object the symbol properties to update

Returns:

• this

updateSceneConfig(idx, sceneConfig)

Updates the sceneConfig of the render plugin with index idx.

layer.updateSceneConfig(0, { collision: false });

Parameters:

• idx Number the render plugin index
• sceneConfig Object the sceneConfig properties to update

Returns:

• this

updateFeatureSceneConfig(idx, styleIdx, sceneConfig)

Updates the sceneConfig of the render plugin with index styleIdx in the feature style with index idx.

const style = {
  featureStyle: [
    {
      id: 16,
      style: [
        {
          renderPlugin: {
            dataConfig: {
              type: 'fill'
            },
            sceneConfig: {
              antialias: false
            },
            type: 'fill'
          },
          symbol: {
            polygonFill: '#f00'
          }
        }
      ]
    }
  ]
}
layer.updateFeatureSceneConfig(0, 0, { antialias: true });

Parameters:

• idx Number the index of the feature style in featureStyle
• styleIdx Number the render plugin index
• sceneConfig Object the sceneConfig properties to update

Returns:

• this

updateDataConfig(idx, dataConfig)

Updates the dataConfig of the render plugin with index idx.

layer.updateDataConfig(0, { altitudeProperty: 'height' });

Parameters:

• idx Number the render plugin index
• dataConfig Object the dataConfig properties to update

Returns:

• this

updateFeatureDataConfig(idx, styleIdx, dataConfig)

Updates the dataConfig of the render plugin with index styleIdx in the feature style with index idx.

const style = {
  featureStyle: [
    {
      id: 16,
      style: [
        {
          renderPlugin: {
            dataConfig: {
              type: 'fill'
            },
            sceneConfig: {
              antialias: false
            },
            type: 'fill'
          },
          symbol: {
            polygonFill: '#f00'
          }
        }
      ]
    }
  ]
}
layer.updateFeatureDataConfig(0, 0, { foo: 1 });

Parameters:

• idx Number the index of the feature style in featureStyle
• styleIdx Number the render plugin index
• dataConfig Object the dataConfig properties to update

Returns:

• this

identify(coordinates, options)

Queries data at the given coordinate on the layer. Note that only rendered data can be queried.

layer.identify([121.23, 39.34], { tolerance: 2 })

Parameters:

• coordinates Number[] the coordinate value
• options Object options, the possible properties are: | Property | Type | Description | Default | | ------ | :----: | ---- | :-----------: | | tolerance | Number | The pixel tolerance for the query | 3 |

Returns:

• Object[]

identifyAtPoint(containerPoint, options)

Queries data at the given container point on the layer.

layer.identifyAtPoint([400, 300], { tolerance: 2 })

Parameters:

• coordinates Number[] the coordinate value
• options Object options, the possible properties are:

Property	Type	Description	Default
tolerance	Number	The pixel tolerance for the query	3

Returns:

• Object[]

getDataSchema(zoom)

Gets the layer definition and property definition at the given zoom level.

Note that the schema of a zoom level can only be fetched after tiles of that level have been loaded; the data schema of a zoom level whose tiles have never been loaded cannot be fetched.

const schema = layer.getDataSchema(8);

Parameters:

• zoom Number the tile zoom level

Returns:

• Object[]

Methods Inherited from TileLayer

See the API documentation of the parent class TileLayer for details.

getTileSize()

Gets the tile width and height.

Returns:

• Size

getTiles()

Gets the tiles.

Returns:

• Object

getTileUrl(x, y, z)

Gets the tile URL.

Returns:

• String

clear()

Clears the layer.

toJSON()

Gets the JSON object of the layer, which can be restored to a layer object with the maptalks.Layer.fromJSON(json) method.

Returns:

• Object

getSpatialReference()

Gets the spatial reference of the layer.

Returns:

• SpatialReference

Methods Inherited from Layer

See the API documentation of the parent class Layer for details.

getId()

Gets the layer id.

Returns:

• Number | String

setId(id)

Sets the layer id.

Returns:

• this

addTo(map)

Adds the layer to the map.

Returns:

• this

getMinZoom()

Gets the minimum zoom level.

Returns:

• Number

getMaxZoom()

Gets the maximum zoom level.

Returns:

• Number

getMap()

Gets the map object that the layer is added to.

Returns:

• Map

getProjection()

Gets the projection of the layer.

Returns:

• Projection

show()

Shows the layer.

Returns:

• this

hide()

Hides the layer.

Returns:

• this

isVisible()

Checks whether the layer is visible.

Returns:

• Boolean

remove()

Removes the layer.

Returns:

• this

on(events, handler, context)

Registers an event listener on the layer.

Returns:

• this

addEventListener(events, handler, context)

Same as the on method.

Returns:

• this

once(events, handler, context)

Registers a one-time event listener on the layer; it is removed after being fired.

Returns:

• this

off(events, handler, context)

Removes the registered event listener from the layer.

Returns:

• this

removeEventListener(events, handler, context)

Same as the off method.

Returns:

• this

listens(events, handler, context)

Checks whether the layer is listening to the given events.

Returns:

• Boolean

fire(event, params)

Manually fires an event; params is the event parameter.

Returns:

• this

setOptions(options)

Sets the layer options.

Returns:

• this

config(key, value)

Updates a layer option.

Returns:

• this

Static Methods

compressStyleJSON(style)

Compresses the style JSON into a smaller JSON object by merging render plugins with identical definitions.

const compressedStyle = GeoJSONVectorTileLayer.compressStyleJSON(style);

Parameters:

• style Object the style object

Returns:

• Object

registerPlugin(Plugin)

Registers a new render plugin.

GeoJSONVectorTileLayer.registerPlugin(PluginClazz);

Parameters:

• PluginClazz PainterPlugin the render plugin class to register

getPlugins()

Gets all registered render plugins.

const pluginClasses = GeoJSONVectorTileLayer.getPlugins();

Returns:

• PainterPlugin[]

fromJSON(json)

Creates a GeoJSONVectorTileLayer object from the layer's JSON object.

const json = layer.toJSON();

const layerCopied = maptalks.Layer.fromJSON(json);

Returns:

• GeoJSONVectorTileLayer

Events

Example code for listening to layer events:

// 监听workerready事件
layer.once('workerready', e => {
  // e为事件参数
  console.log('worker is ready');
});

// 监听tileload事件
layer.on('tileload', e => {
  // e为事件参数
  console.log('loaded a tile', e.tile);
});

Layer Events

dataload

Fired when data is loaded successfully.

Properties:

Property	Type	Value
type	String	"dataload"
target	GeoJSONVectorTileLayer	this
extent	Number[]	the extent range of the data

dataerror

Fired when a data loading error occurs.

Properties:

Property	Type	Value
type	String	"dataerror"
target	GeoJSONVectorTileLayer	this
error	String	the error message

Events Inherited from VectorTileLayer

iblupdated

Fired when the ambient light is updated.

Properties:

Property	Type	Value
type	String	"iblupdated"
target	VectorTileLayer	this

canvasisdirty

Fired when the layer canvas is redrawn.

Properties:

Property	Type	Value
type	String	"canvasisdirty"
target	VectorTileLayer	this

workerready

Fired when the worker is ready.

Properties:

Property	Type	Value
type	String	"workerready"
target	VectorTileLayer	this

datareceived

Fired when tile data is received.

Properties:

Property	Type	Value
type	String	"datareceived"
target	VectorTileLayer	this
url	String	the URL of the tile data

pluginsinited

Fired when the render plugins finish initialization.

Properties:

Property	Type	Value
type	String	"pluginsinited"
target	VectorTileLayer	this

setstyle

Fired when the style is set.

Properties:

Property	Type	Value
type	String	"setstyle"
target	VectorTileLayer	this
style	Object[]	the style object
computedStyle	Object[]	the processed style object

updatesceneconfig

Fired on updatesceneconfig.

Properties:

Property	Type	Value
type	String	"updatesceneconfig"
target	VectorTileLayer	this
index	Number	the style index
sceneConfig	Object	the sceneConfig object

updatefeaturesceneconfig

Fired on updatefeaturesceneconfig.

Properties:

Property	Type	Value
type	String	"updatefeaturesceneconfig"
target	VectorTileLayer	this
index	Number	the feature style index
styleIdx	Number	the feature render plugin index
sceneConfig	Object	the sceneConfig object

updatedataconfig

Fired on updatedataconfig.

Properties:

Property	Type	Value
type	String	"updatedataconfig"
target	VectorTileLayer	this
index	Number	the style index
dataConfig	Object	the dataConfig object

updatefeaturedataconfig

Fired on updatefeaturedataconfig.

Properties:

Property	Type	Value
type	String	"updatefeaturedataconfig"
target	VectorTileLayer	this
index	Number	the feature style index
styleIdx	Number	the feature render plugin index
dataConfig	Object	the dataConfig object

updatesymbol

Fired on updatesymbol.

Properties:

Property	Type	Value
type	String	"updatesymbol"
target	VectorTileLayer	this
index	Number	the style index
symbol	Object	the symbol object

updatefeaturesymbol

Fired on updatefeaturesymbol.

Properties:

Property	Type	Value
type	String	"updatefeaturesymbol"
target	VectorTileLayer	this
index	Number	the feature style index
featureStyleIndex	Number	the feature render plugin index
symbol	Object	the symbol object

Events Inherited from TileLayer

tileload

Fired when a tile is loaded.

Properties:

Property	Type	Value
type	String	"tileload"
target	VectorTileLayer	this
tile	Object	the tile object
tileImage	Object	the tile image data

tileerror

Fired when a tile fails to load.

Properties:

Property	Type	Value
type	String	"tileerror"
target	VectorTileLayer	this
error	String	the error message
tile	Object	the tile object

Events Inherited from Layer

clear

Fired when the layer is cleared.

Properties:

Property	Type	Value
type	String	"clear"
target	VectorTileLayer	this

idchange

Fired when the layer id changes.

Properties:

Property	Type	Value
type	String	"idchange"
target	VectorTileLayer	this
old	String	the old id
new	String	the new id

renderercreate

Fired when the renderer is created.

Properties:

Property	Type	Value
type	String	"renderercreate"
target	VectorTileLayer	this
renderer	VectorTileLayerRenderer

canvascreate

Fired when the canvas is created.

Properties:

Property	Type	Value
type	String	"canvascreate"
target	VectorTileLayer	this
gl	WebGLRenderingContext2D

renderstart

Fired when rendering starts.

Properties:

Property	Type	Value
type	String	"renderstart"
target	VectorTileLayer	this

renderend

Fired when rendering ends.

Properties:

Property	Type	Value
type	String	"renderend"
target	VectorTileLayer	this

This document has been cross-checked against the @maptalks/gl-layers 2026 source code (api-notes-vt-gl.md)