react-mapbox-gl-performance-layers

React wrapper around mapbox-gl-performance-layers library.

Usage no npm install needed!

<script type="module">
  import reactMapboxGlPerformanceLayers from 'https://cdn.skypack.dev/react-mapbox-gl-performance-layers';
</script>

README

react-mapbox-gl-performance-layers

React wrapper around mapbox-gl-performance-layers library.

Features

  • Fast rendering of massive data sets. (Render up to 10 million GeoJSON points.)
  • Support for Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon geometry types.
  • Data driven size, color, opacity, outlineSize, outlineColor and outlineOpacity.
  • Automatic switching between direct rendering for small data sets and tiled rendering for large data sets.
  • Option to sacrifice quality for performance using the simpleRendering option.

Installation

$ npm install mapbox-gl-performance-layers
$ npm install react-mapbox-gl-performance-layers

This library already contains TypeScript types. There is no need to add @types/react-mapbox-gl-performance-layers to your TypeScript project.

Basic Usage

Point layer (for static Point and MultiPoint geometry):

import {PointLayer} from 'react-mapbox-gl-performance-layers';

function Component() {
    return (
        <Map>
            <PointLayer
                data={pointFeatureCollection}
                style={{/*style properties*/}}
            />
        </Map>
    );
}

Line layer (for static LineString and MultiLineString geometry):

import {LineLayer} from 'react-mapbox-gl-performance-layers';

function Component() {
    return (
        <Map>
            <LineLayer
                data={lineStringFeatureCollection}
                style={{/*style properties*/}}
            />
        </Map>
    );
}

Polygon layer (for static Polygon and MultiPolygon geometry):

import {PolygonLayer} from 'react-mapbox-gl-performance-layers';

function Component() {
    return (
        <Map>
            <PolygonLayer
                data={polygonFeatureCollection}
                style={{/*style properties*/}}
            />
        </Map>
    );
}

Dynamic point layer (for Point and MultiPoint geometry streams):

import {DynamicPointLayer} from 'react-mapbox-gl-performance-layers';

function Component() {
    const dataOperationsRef = useRef(null);
    
    useEffect(() => {
        const intervalId = setInterval(() => {
            const data = dataOperationsRef.current;
            if (data != null) {
                data.add(pointFeature);
            }
        }, 1000);
        return () => clearInterval(intervalId);
    }, []);
    
    return (
        <Map>
            <DynamicPointLayer
                data={dataOperations => dataOperationsRef.current = dataOperations}
                style={getStyle}
            />
        </Map>
    );
}

API Documentation

Point Layer Props

Dynamic Props

  • data: FeatureCollection<Point | MultiPoint, P> | null | undefined
    • Data that is to be rendered.
    • Setting to null or undefined will clear the data.
    • Expensive to change for large data sets.
    • Automatically repaints the map on change.
  • style?: undefined | Partial<PointStyle> | (feature: Feature<Point | MultiPoint, P>) => Partial<PointStyle>
    • Style that's used to display the data.
    • By setting to undefined one can set the style to default value.
    • By setting to a object one can override individual properties of the default style.
    • By setting to a function one can use data driven styling.
    • Function is evaluated immediately and is reevaluated only if data gets changed.
    • Expensive to change for large data sets.
    • Automatically repaints the map on change.
  • visibility?: boolean | ((map: mapboxgl.Map) => boolean) | undefined | null
    • Layer's visibility.
    • By setting a boolean one can programmatically show/hide the layer.
    • By setting a function one can show/hide the layer based on the current zoom level or viewport.
  • before?: string
    • Mapbox GL JS ID of the layer before witch this layer is to be inserted.
    • If no layer with such ID is found a exception will be thrown.
    • Changing this value will result in the layer being removed and added back to the map.
  • onClick?: (feature: Feature<Point | MultiPoint, P>, e: MapMouseEvent & EventData) => void
    • Function that is called when user clicks on a feature.
    • This prop is not entirely dynamic.
    • If the initial value of this prop is undefined the component will enter a reduced memory usage mode.
    • In the reduced memory usage mode this prop dose not respond to future changes of value.
    • If the initial value of this prop is a function the prop responds to future changes of value.

Static Props

  • id?: string
    • Mapbox GL JS layer ID.
    • If left undefined the ID is automatically generated by react-mapbox-gl.
  • simpleRendering?: boolean
    • Whether or not to use simpler (faster) rendering method.
    • This simple rendering may disable some of the style properties.
    • Defaults to false.
  • interpolation?: number
    • Amount of space in pixels used for color interpolation (anti-aliasing).
    • Defaults to 1.8.
  • tileThreshold?: number
    • Number of features required for the layer to switch from direct rendering mode to tiled rendering mode.
    • Defaults to 100000.
  • numberOfTiles?: number
    • Number of tiles cashed while using tiled rendering mode.
    • Defaults to 16.
  • tileWidth?: number
    • Tile texture width in pixels.
    • Defaults to 2048.
  • tileHeight?: number
    • Tile texture height in pixels.
    • Defaults to 2048.

LineString Layer Props

Dynamic Props

  • data: FeatureCollection<LineString | MultiLineString, P> | null | undefined
    • Data that is to be rendered.
    • Setting to null or undefined will clear the data.
    • Expensive to change for large data sets.
    • Automatically repaints the map on change.
  • style?: undefined | Partial<LineStyle> | (feature: Feature<LineString | MultiLineString, P>) => Partial<LineStyle>
    • Style that's used to display the data.
    • By setting to undefined one can set the style to default value.
    • By setting to a object one can override individual properties of the default style.
    • By setting to a function one can use data driven styling.
    • Function is evaluated immediately and is reevaluated only if data gets changed.
    • Expensive to change for large data sets.
    • Automatically repaints the map on change.
  • visibility?: boolean | ((map: mapboxgl.Map) => boolean) | undefined | null
    • Layer's visibility.
    • By setting a boolean one can programmatically show/hide the layer.
    • By setting a function one can show/hide the layer based on the current zoom level or viewport.
  • before?: string
    • Mapbox GL JS ID of the layer before witch this layer is to be inserted.
    • If no layer with such ID is found a exception will be thrown.
    • Changing this value will result in the layer being removed and added back to the map.
  • onClick?: (feature: Feature<LineString | MultiLineString, P>, e: MapMouseEvent & EventData, , closestPointOnLine: {x: number, y: number}) => void
    • Function that is called when user clicks on a feature.
    • This prop is not entirely dynamic.
    • If the initial value of this prop is undefined the component will enter a reduced memory usage mode.
    • In the reduced memory usage mode this prop dose not respond to future changes of value.
    • If the initial value of this prop is a function the prop responds to future changes of value.

Static Props

  • id?: string
    • Mapbox GL JS layer ID.
    • If left undefined the ID is automatically generated by react-mapbox-gl.
  • simpleRendering?: boolean
    • Whether or not to use simpler (faster) rendering method.
    • This simple rendering may disable some of the style properties.
    • Defaults to false.
  • interpolation?: number
    • Amount of space in pixels used for color interpolation (anti-aliasing).
    • Defaults to 1.8.
  • tileThreshold?: number
    • Number of features required for the layer to switch from direct rendering mode to tiled rendering mode.
    • Defaults to 10000.
  • numberOfTiles?: number
    • Number of tiles cashed while using tiled rendering mode.
    • Defaults to 16.
  • tileWidth?: number
    • Tile texture width in pixels.
    • Defaults to 2048.
  • tileHeight?: number
    • Tile texture height in pixels.
    • Defaults to 2048.

Polygon Layer Props

Dynamic Props

  • data: FeatureCollection<Polygon | MultiPolygon, P> | null | undefined
    • Data that is to be rendered.
    • Setting to null or undefined will clear the data.
    • Expensive to change for large data sets.
    • Automatically repaints the map on change.
  • style?: undefined | Partial<PolygonStyle> | (feature: Feature<Polygon | MultiPolygon, P>) => Partial<PolygonStyle>
    • Style that's used to display the data.
    • By setting to undefined one can set the style to default value.
    • By setting to a object one can override individual properties of the default style.
    • By setting to a function one can use data driven styling.
    • Function is evaluated immediately and is reevaluated only if data gets changed.
    • Expensive to change for large data sets.
    • Automatically repaints the map on change.
  • visibility?: boolean | ((map: mapboxgl.Map) => boolean) | undefined | null
    • Layer's visibility.
    • By setting a boolean one can programmatically show/hide the layer.
    • By setting a function one can show/hide the layer based on the current zoom level or viewport.
  • before?: string
    • Mapbox GL JS ID of the layer before witch this layer is to be inserted.
    • If no layer with such ID is found a exception will be thrown.
    • Changing this value will result in the layer being removed and added back to the map.
  • onClick?: (feature: Feature<Polygon | MultiPolygon, P>, e: MapMouseEvent & EventData) => void
    • Function that is called when user clicks on a feature.
    • This prop is not entirely dynamic.
    • If the initial value of this prop is undefined the component will enter a reduced memory usage mode.
    • In the reduced memory usage mode this prop dose not respond to future changes of value.
    • If the initial value of this prop is a function the prop responds to future changes of value.

Static Props

  • id?: string
    • Mapbox GL JS layer ID.
    • If left undefined the ID is automatically generated by react-mapbox-gl.
  • simpleRendering?: boolean
    • Whether or not to use simpler (faster) rendering method.
    • This simple rendering may disable some of the style properties.
    • Defaults to false.
  • interpolation?: number
    • Amount of space in pixels used for color interpolation (anti-aliasing).
    • Defaults to 1.8.
  • tileThreshold?: number
    • Number of features required for the layer to switch from direct rendering mode to tiled rendering mode.
    • Defaults to 10000.
  • numberOfTiles?: number
    • Number of tiles cashed while using tiled rendering mode.
    • Defaults to 16.
  • tileWidth?: number
    • Tile texture width in pixels.
    • Defaults to 2048.
  • tileHeight?: number
    • Tile texture height in pixels.
    • Defaults to 2048.

Dynamic Point Layer

Dynamic Point Layer Props

  • data: (dataOperations: DataOperations<Feature<Point | MultiPoint, P>>) => void
    • Callback prop used to retrieve the reference to data operations object.
    • Data operations object is used to interact with layers internal data.
    • The callback is called immediately when the component gets constructed.
  • The remaining props are identical to Point Layer Props.

Dynamic Point Data Operations

  • add(element: Feature<Point | MultiPoint>): void
    • Adds the specified feature to the data set.
  • removeFirst(): Feature<Point | MultiPoint> | null
    • Removes the earliest added feature from the data set.
  • removeLast(): Feature<Point | MultiPoint> | null
    • Removes the latest added feature from the data set.
  • clear(): void
    • Removes all features from the data set.
  • getArray(): ReadonlyArray<Feature<Point | MultiPoint>>
    • Returns a readonly array of all features in the dataset.
    • This operation is not expensive.
    • Since the array is readonly modifying it is not advised.
  • addAll(elements: Feature<Point | MultiPoint>[]): void
    • Adds multiple specified features to the data set.
  • removeNFirst(n: number): Feature<Point | MultiPoint>[]
    • Removes n earliest added features from the data set.
  • removeNLast(n: number): Feature<Point | MultiPoint>[]
    • Removes n latest added features from the data set.

Styles

Point Style Properties

  • size: number
    • Point diameter in pixels.
    • Defaults to 10.
  • color: {r: number, g: number, b: number}
    • Fill color.
    • Value of each channel is in [0, 1] interval.
    • Defaults to {r: 0, g: 0, b: 1}.
  • opacity: number
    • Fill opacity.
    • Value is in [0, 1] interval.
    • Defaults to 0.8.
  • outlineSize: number
    • Size of the outline in pixels.
    • Defaults to 0.
    • Not available on simple rendering mode.
  • outlineColor: {r: number, g: number, b: number}
    • Outline color.
    • Defaults to {r: 0, g: 0, b: 0}.
    • Not available on simple rendering mode.
  • outlineOpacity: number
    • Outline opacity.
    • Defaults to 0.8.
    • Not available on simple rendering mode.

Line Style Properties

  • size: number
    • Line width in pixels.
    • Defaults to 5.
    • Not available on simple rendering mode.
  • color: {r: number, g: number, b: number}
    • Fill color.
    • Value of each channel is in [0, 1] interval.
    • Defaults to {r: 0, g: 0, b: 1}.
  • opacity: number
    • Fill opacity.
    • Value is in [0, 1] interval.
    • Defaults to 0.8.
  • outlineSize: number
    • Size of the outline in pixels.
    • Defaults to 0.
    • Not available on simple rendering mode.
  • outlineColor: {r: number, g: number, b: number}
    • Outline color.
    • Defaults to {r: 0, g: 0, b: 0}.
    • Not available on simple rendering mode.
  • outlineOpacity: number
    • Outline opacity.
    • Defaults to 0.8.
    • Not available on simple rendering mode.

Polygon Style Properties

  • color: {r: number, g: number, b: number}
    • Fill color.
    • Value of each channel is in [0, 1] interval.
    • Defaults to {r: 0, g: 0, b: 1}.
  • opacity: number
    • Fill opacity.
    • Value is in [0, 1] interval.
    • Defaults to 0.8.
  • outlineSize: number
    • Size of the outline in pixels.
    • Defaults to 0.
    • Not available on simple rendering mode.
  • outlineColor: {r: number, g: number, b: number}
    • Outline color.
    • Defaults to {r: 0, g: 0, b: 0}.
    • Not available on simple rendering mode.
  • outlineOpacity: number
    • Outline opacity.
    • Defaults to 0.8.
    • Not available on simple rendering mode.

Dynamic Point Style Properties

  • Identical to Point Style Properties.