Layers

Layers are responsible for rendering data associated with a data source based on a particular style configuration. There are two primary components to a layer: the source that provides the data to render, and a layer style that determines how that data gets rendered on a map. Currently, all layers within MapsGL are TileLayer instances.

Review our advanced section on layers for more information and examples on setting up and using custom layers.

Layer

The base class for all layers on a map.

Configuration

{
    type: LayerType;
    source: string | SourceSpecification | DataSource;
    sourceLayer: string;
    sourceType: SourceType;
    timeMode: TimeSeriesMode;
    timeRange: TimeRange;
    paint: Partial<PaintStyleSpec>;
}

The following configuration options are supported when instantiating Layer instances and subclasses:

Option	Description	Default
`type`	Type: `raster \| circle \| symbol \| fill \| line \| sample \| grid \| heatmap \| contour \| particles` (required)The type of style to use when rendering the layer. See the list of available layer styles for examples of each type.
`source`	Type: `string` (required)The identifier of the data source to be used for the layer.
`sourceLayer`	Type: `string` ()Layer name to use from a `vector` tile data source that corresponds to the features to render for the layer.
`sourceType`	Type: `point \| line \| polygon \| symbol` ()The feature type to use from the `sourceLayer` when using a `vector` tile data source.
`paint`	Type: `PaintStyleSpec` (required)Style configuration for the layer. See the list of available layer styles and their properties. Also, review the mapping of layer `type` values to the supported `paint` style options for that type.
`timeMode`	Type: `none \| past \| future \| range \| any` ()Controls how a time-based layer is rendered relative to the timeline associated with the parent `MapController`: - `none`: layer is not time-specific - `past`: layer is only for time intervals in the past - `future`: layer is only for time intervals in the future - `range`: layer is only for a specified time range as defined by `timeRange` - `any`: layer is time-based but for any time interval	`none`
`timeRange`	Type: `{ start: Date; end: Date; }` ()For time-based layers, defines the valid time range for the layer when `timeMode` is set to `range`.

Properties

The following properties are available on Layer instances and subclasses:

Option	Description	Default
`style`	Type: `PaintStyle` ()Paint style configuration associated with the layer.
`visible`	Type: `boolean` (read-only)Whether the layer is currently visible. To change the visibility of a layer, use the `show()` and `hide()` methods.	`true`
`enabled`	Type: `boolean` ()Whether the layer is enabled.	`true`
`metadata`	Type: `Record<string, any>` (read-only)Returns metadata information about the layer, such as its identifier, type, source, filters and paint style.
`renderer`	Type: `LayerRenderer` (read-only)Layer style renderer associated with the layer as determined by the layer's configured `type`.
`animator`	Type: `TimeSeriesAnimator` (optional)Manages time series data and requests associated with a time-based data source and layer. If the layer is not time-based, then `undefined` will be returned.
`isDirty`	Type: `boolean` (read-only)Returns whether the layer has been flagged as dirty, indicating it will be updated during the next rendered frame.	`false`

Methods

show()

hide()

refresh(clear: boolean)

setPaintProperty(property: string, value: any)

setNeedsUpdate()

queryFeatures(coord: { lat: number; lon: number; }, zoom: number): number | Record<string, any> | Array<any>

queryFeaturesPromise(coord: { lat: number; lon: number; }, zoom: number): Promise<FeatureQueryResult | void>

dispose()

Styles

Paint styles are used to control the visual appearance of a layer and are provided using a layer's paint configuration property.

Layer type values aren't necessarily directly mapped to style properties as multiple style properties may be used for a single layer type. For example, a fill layer type will only use the fill style properties, but a circle layer type will use the circle, fill, and stroke style properties. However, all layer types will use the root-level opacity style property to control the layer's overall transparency.

The following table provides a list of available layer types and their associated style properties. For a complete list of available style properties and their descriptions, see the style reference.

Layer Type	Style Properties
`raster`	`raster`
`fill`	`fill`, `stroke`*
`line`	`stroke`
`circle`	`circle`, `fill`, and `stroke`
`symbol`	`symbol`
`sample`	`sample`
`grid`	`grid` and `sample`
`contour`	`contour` and `sample`
`particles`	`particle` and `sample`
`heatmap`	`heatmap`

* When used with fill, stroke only supports color and opacity style properties.

Tile Layer

A layer that renders raster, encoded or vector tiles on a map. Extends Layer.

Configuration

{
    type: LayerType;
    source: string | SourceSpecification | DataSource;
    sourceLayer: string;
    sourceType: SourceType;
    timeMode: TimeSeriesMode;
    timeRange: TimeRange;
    quality: DataQuality;
    paint: Partial<PaintStyleSpec>;
}

The following configuration options are supported when instantiating TileLayer instances:

Option	Description	Default
`quality`	Type: `exact` ()xxxxxx	`xxxxxx`

Properties

The following properties are available on TileLayer instances and subclasses:

Option	Description	Default
`quality`	Type: `DataQuality` ()Data resolution to use, which controls which data zoom level is requested for a specific map zoom level. Using a lower data quality value will reduce the amount of data needed for the visible map region but also result is lower data resolution. Using a higher quality value will provide the most accurate result and highest data resolution but also increase the amount of data required. A lower quality value is useful in environments where resource limitations exist, such as mobile devices or less capable hardware.	`exact`

Methods

getDataZoom(zoom: number): number

Data Sources Styles