Map Component

← Back to Documentation

The Map component renders an interactive map using MapLibre GL JS. Vector layers can be added via the vectorLayers prop or shorthand props like geojson, csv, directus, etc. Layers can include searchable fields for advanced filtering.

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 Vector Layers

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

1
<Map
2
  client:only="react"
3
  height="600px"
4
  scaleControl="bottom-left"
5
  vectorLayers={[
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
/>

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
/>

Vector Layer Search

Vector Layers with Search

Enable per-layer search by setting searchInFields on a vector 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
  vectorLayers={[
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)
`vectorLayers`	`VectorLayerConfig[]`	—	Vector data 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'

VectorLayerConfig

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

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
}