Layers

Layers render data on the map — points, lines, and polygons with static or data-driven styling.

Supported layer types: geojson, parquet, route, heatmap, mvt, and raster. For route lines, see Routes. For heatmaps, see Heatmap. For tile layers, see Tile Layers.

Basic Usage

{
  "layers": {
    "buildings": {
      "type": "geojson",
      "data": "https://example.com/buildings.geojson",
      "style": {
        "fillColor": "#3498db",
        "opacity": 0.6,
        "lineColor": "#2980b9",
        "lineWidth": 1
      },
      "tooltip": ["name", "height"]
    }
  }
}

Properties

Property	Type	Required	Description
`type`	`"geojson"`	Yes	Layer type
`data`	`string \| object`	Yes	GeoJSON URL or inline GeoJSON object
`style`	`LayerStyle`	No	Visual style for the layer
`tooltip`	`string[]`	No	Feature property names to show on hover
`cluster`	`boolean`	No	Enable point clustering
`clusterOptions`	`ClusterOptions`	No	Clustering configuration

Style Properties

Property	Type	Default	Description
`fillColor`	`ColorValue`	`"#3b82f6"`	Polygon fill color
`pointColor`	`ColorValue`	(uses fillColor)	Point circle color
`lineColor`	`ColorValue`	`"#333333"`	Line / polygon outline color
`lineWidth`	`number`	`1`	Line width in pixels
`pointRadius`	`SizeValue`	`5`	Point circle radius in pixels
`opacity`	`number`	`0.8`	Overall opacity (0–1)

A ColorValue can be a static hex string or a data-driven mapping. See Color System.

A SizeValue can be a static number or a data-driven continuous mapping:

{
  "pointRadius": {
    "type": "continuous",
    "attr": "mag",
    "domain": [0, 8],
    "range": [2, 12]
  }
}

Clustering

Enable point clustering to group nearby points at lower zoom levels:

{
  "layers": {
    "stores": {
      "type": "geojson",
      "data": "https://example.com/stores.geojson",
      "cluster": true,
      "clusterOptions": {
        "radius": 50,
        "maxZoom": 14,
        "minPoints": 2,
        "colors": ["#22c55e", "#eab308", "#ef4444"]
      }
    }
  }
}

Option	Type	Default	Description
`radius`	`number`	`50`	Cluster radius in pixels
`maxZoom`	`number`	`14`	Max zoom level for clustering
`minPoints`	`number`	`2`	Minimum points per cluster
`colors`	`[string, string, string]`	green/yellow/red	Colors for small/medium/large clusters

Geometry Handling

A single GeoJSON source can contain mixed geometry types. The renderer automatically creates:

Fill sublayer for Polygon / MultiPolygon features
Line sublayer for all features (outlines + LineString)
Circle sublayer for Point / MultiPoint features

Data Sources

URL string — fetched at render time:

{ "data": "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson" }

Inline GeoJSON — embedded in the spec:

{
  "data": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": { "type": "Point", "coordinates": [-73.98, 40.75] },
        "properties": { "name": "NYC" }
      }
    ]
  }
}

GeoParquet Layers

Load GeoParquet files directly from a URL. The geometry column is auto-detected from GeoParquet metadata, and the map auto-fits to the data bounds.

{
  "layers": {
    "buildings": {
      "type": "parquet",
      "data": "https://example.com/buildings.parquet",
      "style": {
        "fillColor": "#3b82f6",
        "opacity": 0.7
      }
    }
  }
}

Property	Type	Required	Description
`type`	`"parquet"`	Yes	Layer type
`data`	`string`	Yes	URL to a GeoParquet file
`geometryColumn`	`string`	No	Geometry column name (auto-detected if omitted)
`style`	`LayerStyle`	No	Same style system as GeoJSON layers
`tooltip`	`string \| string[]`	No	Property names to show on hover (all columns if omitted)
`cluster`	`boolean`	No	Enable point clustering
`clusterOptions`	`ClusterOptions`	No	Clustering configuration

Parquet layers support zstd, brotli, gzip, lz4, and snappy compression. The file is fetched client-side and converted to GeoJSON internally.

Data-Driven Color

See Color System for full documentation. Quick examples:

Continuous — numeric property to gradient:

{ "fillColor": { "type": "continuous", "attr": "population", "palette": "Sunset", "domain": [0, 1000000] } }

Categorical — string property to discrete colors:

{ "fillColor": { "type": "categorical", "attr": "zone_type", "palette": "Bold" } }

Legend

When a layer has data-driven color, you can add an auto-generated legend. See Legend.

Events

Layer clicks fire the onLayerClick callback. See Events.

Example

Live USGS earthquake data with magnitude-based coloring: