Map Component

← Back to Documentation

The Map component renders an interactive map using MapLibre GL JS (v6). Overlay layers — GeoJSON, CSV, Directus, a generic API, or raster XYZ/WMS tiles — can be added via the overlayLayers prop or shorthand props like geojson, csv, directus, etc. Layers can include searchable fields for advanced filtering.

Requirements: MapLibre GL JS v6 needs WebGL2 (supported by every current browser; the map can’t render where WebGL2 is unavailable or disabled). The MapLibre Web Worker is configured automatically by @lad-sapienza/scms-core, so a consuming site needs no bundler or worker setup of its own.

Live Examples

Simple map with base layers

The most basic Map configuration. Displays a map centered on coordinates 37,37 (Turkey) at zoom 8 with two switchable basemap layers.

Available basemap shorthand values: CAWM, OSM, EsriSatellite, EsriStreets, EsriTopo, GoogleSatellite, GoogleRoadmap, GoogleTerrain, GoogleAlteredRoadmap, CartoDB, StamenTerrain, OSMMapnick, OSMCycle.

1
<Map
2
  client:only="react"
3
  height="500px"
4
  center="37,37,8"
5
  baseLayers={['EsriSatellite', 'GoogleTerrain']}
6
/>

Custom basemap configuration

Instead of shorthand keys, provide full configuration objects with name, url, and optional attribution:

1
<Map
2
  client:only="react"
3
  height="500px"
4
  center="37,37,8"
5
  baseLayers={[
6
    {
7
      name: "Esri Topo",
8
      url: "https://server.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/tile/{z}/{y}/{x}",
9
    },
10
    'GoogleSatellite'
11
  ]}
12
/>

Adding map controls

Add navigation, scale, fullscreen, and layer-switcher controls using their respective props. Each accepts a position string (top-right, top-left, bottom-right, bottom-left).

1
<Map
2
  client:only="react"
3
  height="500px"
4
  center="37,37,8"
5
  navigationControl="top-left"
6
  scaleControl="bottom-left"
7
  fullscreenControl="top-right"
8
  layerControl="top-right"
9
  baseLayers={['EsriSatellite', 'GoogleTerrain']}
10
/>

Load geo-data from a GeoJSON file

Use the geojson shorthand prop to load a GeoJSON file directly. fitToContent: true automatically zooms the map to show all features.

1
<Map
2
  client:only="react"
3
  height="500px"
4
  geojson={{
5
    name: "Kahramanmaraş Survey Sites",
6
    path: "/data/ksa.geojson",
7
    popup: "<b>${Site_Name}</b><br/>${Description}",
8
    fitToContent: true,
9
    style: {
10
      type: 'circle',
11
      paint: {
12
        'circle-radius': 4,
13
        'circle-color': '#ff6b6b',
14
        'circle-stroke-width': 1,
15
        'circle-stroke-color': '#ffffff'
16
      }
17
    }
18
  }}
19
  baseLayers={['EsriSatellite', 'GoogleTerrain']}
20
/>

Load geo-data from a CSV file

Load point data from a CSV file. Use lng and lat to specify which columns contain the coordinates.

1
<Map
2
  client:only="react"
3
  height="500px"
4
  center="37,37,8"
5
  csv={{
6
    path: "/data/ksa.csv",
7
    lng: "Longitude",
8
    lat: "Latitude",
9
    popup: "<b>${Site_Name}</b><br/>${Description}",
10
    style: {
11
      type: 'circle',
12
      paint: {
13
        'circle-radius': 8,
14
        'circle-color': '#4ecdc4',
15
        'circle-stroke-width': 2,
16
        'circle-stroke-color': '#ffffff'
17
      }
18
    }
19
  }}
20
  baseLayers={['EsriSatellite', 'GoogleTerrain']}
21
/>

Client-side filtering with GeoJSON

Filter features client-side using a Directus-like filter object. Supported operators: _eq, _neq, _in, _nin, _contains, _ncontains, _gt, _gte, _lt, _lte, _null, _nnull. Multiple conditions use AND logic.

1
<Map
2
  client:only="react"
3
  height="500px"
4
  geojson={{
5
    path: "/data/ksa.geojson",
6
    name: "Middle Bronze Age Sites",
7
    filter: { Middle_Bronze: { _eq: "true" } },
8
    popup: "<b>${Site_Name}</b><br/>${Description}",
9
    fitToContent: true,
10
    style: {
11
      type: 'circle',
12
      paint: {
13
        'circle-radius': 6,
14
        'circle-color': '#e74c3c',
15
        'circle-stroke-width': 1,
16
        'circle-stroke-color': '#ffffff'
17
      }
18
    }
19
  }}
20
  baseLayers={['EsriSatellite', 'GoogleTerrain']}
21
/>

Multiple Overlay Layers

Add multiple overlay layers (GeoJSON and CSV) with independent styles and popups using the overlayLayers prop:

1
<Map
2
  client:only="react"
3
  height="600px"
4
  scaleControl="bottom-left"
5
  overlayLayers={[
6
    {
7
      name: 'GeoJSON Sites',
8
      source: { type: 'geojson', url: '/data/ksa.geojson' },
9
      popupTemplate: '<b>${Site_Name}</b><br/>${Description}',
10
      fitToContent: true,
11
      style: {
12
        type: 'circle',
13
        paint: { 'circle-radius': 8, 'circle-color': '#ff6b6b' }
14
      }
15
    },
16
    {
17
      name: 'CSV Sites',
18
      source: { type: 'csv', url: '/data/ksa.csv' },
19
      popupTemplate: '<b>${Site_Name}</b>',
20
      style: {
21
        type: 'circle',
22
        paint: { 'circle-radius': 4, 'circle-color': '#4ecdc4' }
23
      }
24
    }
25
  ]}
26
  baseLayers={['EsriSatellite', 'GoogleTerrain']}
27
/>

Raster overlay independent of the basemap

A raster layer (XYZ or WMS tiles) can now be an independent, toggleable overlay instead of only a radio-exclusive basemap — e.g. a satellite or historical map layer shown on top of whichever basemap the user picks. Set source.type to xyz or wms on an overlayLayers entry; it renders as MapLibre raster tiles and shows up as a checkbox in the layer control, separate from the basemap radio group.

Both raster source types need the tile server to send CORS headers — MapLibre uploads tiles as WebGL textures, which browsers refuse cross-origin without a successful CORS check.

1
<Map
2
  client:only="react"
3
  height="500px"
4
  center="37,37,8"
5
  baseLayers={['EsriStreets']}
6
  overlayLayers={[
7
    {
8
      name: 'Satellite',
9
      source: {
10
        type: 'xyz',
11
        url: 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}'
12
      }
13
    },
14
    {
15
      name: 'US States (WMS demo)',
16
      source: {
17
        type: 'wms',
18
        url: 'https://ahocevar.com/geoserver/wms',
19
        layers: 'topp:states'
20
      }
21
    }
22
  ]}
23
/>

Load map from MapLibre style JSON

Load a complete map configuration from a MapLibre style JSON file. The style file can include sources, layers, and full styling:

1
<Map
2
  client:only="react"
3
  height="500px"
4
  center="37,37,8"
5
  mapStyle="/data/ksa.json"
6
/>

Override and expand style JSON layers

Use styleOverrides to override paint/layout properties or add extra features (popupTemplate, fitToContent) to layers defined in a MapLibre style JSON:

1
<Map
2
  client:only="react"
3
  height="500px"
4
  mapStyle="/data/ksa.json"
5
  styleOverrides={{
6
    'ksa': {
7
      paint: { 'circle-color': '#00ff00', 'circle-radius': 8 },
8
      popupTemplate: '<b>${Site_Name}</b>',
9
      fitToContent: true
10
    }
11
  }}
12
/>

Load data from Directus

Load geographical data directly from a Directus collection. geoField specifies which field contains GeoJSON geometry. Filter with Directus query syntax via queryString.

Credentials can be passed directly or via PUBLIC_DIRECTUS_URL / PUBLIC_DIRECTUS_TOKEN env vars.

1
<Map
2
  client:only="react"
3
  height="500px"
4
  center="37,37,8"
5
  directus={{
6
    table: "scms_ksa",
7
    geoField: "geometry",
8
    queryString: "filter[Hellenistic_Roman][_eq]=true",
9
    name: "Hellenistic-Roman Sites",
10
    popup: "<b>${Site_Name}</b><br/>${Description}",
11
    fitToContent: true,
12
    style: {
13
      type: 'circle',
14
      paint: { 'circle-radius': 6, 'circle-color': '#9b59b6' }
15
    }
16
  }}
17
  baseLayers={['EsriSatellite', 'GoogleTerrain']}
18
/>

Overlay Layer Search

Overlay Layers with Search

Enable per-layer search by setting searchInFields on an overlay layer. A search icon appears in the layer control; clicking it opens a search interface supporting both simple free-text and advanced field/operator/value queries.

1
<Map
2
  client:only="react"
3
  height="600px"
4
  overlayLayers={[
5
    {
6
      name: 'Archaeological Sites',
7
      source: { type: 'geojson', url: '/data/ksa.geojson' },
8
      popupTemplate: '<b>${Site_Name}</b><br/>${Item_Label}',
9
      searchInFields: {
10
        Site_Name: "Site Name",
11
        Item_Label: "Item Label",
12
        Site_Description: "Description"
13
      },
14
      fitToContent: true,
15
      style: {
16
        type: 'circle',
17
        paint: { 'circle-radius': 6, 'circle-color': '#ff6b6b' }
18
      }
19
    }
20
  ]}
21
  baseLayers={['EsriSatellite', 'OSM']}
22
/>

Props API

MapProps

Prop	Type	Default	Description
`height`	`string`	`'400px'`	Map height (CSS value)
`center`	`string`	—	Initial center as `"lng,lat,zoom"`
`baseLayers`	`BaseLayerConfig[] \| BasemapKey[]`	—	Base layers (use shorthand keys or full config objects)
`overlayLayers`	`OverlayLayerConfig[]`	—	Independent, toggleable overlay layers
`geojson`	shorthand	—	Shorthand for a single GeoJSON layer
`csv`	shorthand	—	Shorthand for a single CSV layer
`directus`	shorthand	—	Shorthand for a single Directus layer
`mapStyle`	`string \| object`	—	MapLibre style JSON URL or object
`styleOverrides`	`Record<string, LayerOverride>`	—	Override/extend layers from `mapStyle`
`navigationControl`	`ControlPosition`	—	Navigation control position
`scaleControl`	`ControlPosition`	—	Scale bar position
`fullscreenControl`	`ControlPosition`	—	Fullscreen button position
`layerControl`	`boolean \| ControlPosition`	`true`	Layer switcher position
`geolocateControl`	`ControlPosition`	—	Geolocate button position
`sprite`	`string`	—	MapLibre sprite URL

ControlPosition: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'

BaseLayerConfig

Prop	Type	Description
`name`	`string`	Label shown in the layer control
`url`	`string`	Tile URL template, `{z}/{x}/{y}` (optionally with `{s}`, expanded automatically to `a`/`b`/`c`)
`attribution`	`string`	Attribution HTML
`tileSize`	`number`	Tile size in pixels (default: `256`)

OverlayLayerConfig

Prop	Type	Description
`name`	`string`	Layer display name
`source`	`SourceConfig \| XyzSourceConfig \| WmsSourceConfig`	Data source — see below
`style`	`object`	MapLibre paint/layout properties (row/feature sources only)
`popupTemplate`	`string`	HTML popup with `${fieldName}` placeholders (row/feature sources only)
`visible`	`boolean`	Initial visibility (default: `true`)
`fitToContent`	`boolean`	Auto-zoom to layer bounds (row/feature sources only)
`filter`	`FilterObject \| function`	Client-side feature filter (row/feature sources only)
`searchInFields`	`SearchInFields`	Fields to expose in the search UI (row/feature sources only)

source.type is geojson, csv, json, directus, or api for row/feature data (fetched and converted to GeoJSON), or xyz/wms for raster tiles (rendered natively via MapLibre, never fetched — style/popupTemplate/fitToContent/filter/searchInFields don’t apply to these).

The popupTemplate string itself is rendered as-is (so <b>, <a href="...">, etc. work), but every ${fieldName} value substituted into it is HTML-escaped first — safe even when the data comes from a source you don’t fully control (a public Directus collection, a third-party CSV/GeoJSON URL).

If two overlay entries share the exact same source, the underlying fetch happens only once — each layer’s own filter is applied on top of the shared cached data.

XyzSourceConfig / WmsSourceConfig

1
interface XyzSourceConfig {
2
  type: 'xyz';
3
  url: string;           // {z}/{x}/{y}, optionally {s}
4
  tileSize?: number;      // default: 256
5
  attribution?: string;
6
}
7

8
interface WmsSourceConfig {
9
  type: 'wms';
10
  url: string;            // WMS endpoint base URL
11
  layers: string;         // GetMap LAYERS param
12
  format?: string;        // default: 'image/png'
13
  version?: string;       // default: '1.3.0'
14
  transparent?: boolean;  // default: true
15
  styles?: string;
16
  crs?: string;           // default: 'EPSG:3857'
17
  tileSize?: number;      // default: 256
18
  attribution?: string;
19
}

Both raster source types render as an independent overlay — a historical map or satellite layer can be toggled on top of any basemap, rather than only being selectable as the basemap. See the “Raster overlay independent of the basemap” example above.

DirectusShorthand (for Map)

1
interface DirectusShorthand {
2
  table: string;
3
  geoField?: string;       // Field containing GeoJSON geometry
4
  queryString?: string;    // Directus filter query string
5
  name?: string;           // Layer display name
6
  popup?: string;          // Popup HTML template
7
  fitToContent?: boolean;
8
  style?: object;
9
  url?: string;            // defaults to PUBLIC_DIRECTUS_URL
10
  token?: string;          // defaults to PUBLIC_DIRECTUS_TOKEN
11
}