@litforge/arcgis-map

A Lit web component for displaying ArcGIS maps with support for loading layers from ArcGIS Portal.

Overview

The ArcGISMap component provides a wrapper around the ArcGIS Maps SDK for JavaScript, allowing you to easily embed interactive maps in your web applications. It supports:

• Loading layers from ArcGIS Portal
• Customizable basemaps
• Configurable zoom and center
• Loading and error states
• Event handling for map lifecycle
• Layer visibility control - Show/hide specific layers
• Client-side layers - Add GeoJSON, arrays, or CSV data as map layers
• Programmatic layer management - Add, remove, and update layers dynamically

Installation

npm install @litforge/arcgis-map @arcgis/core
# or
pnpm add @litforge/arcgis-map @arcgis/core
# or
yarn add @litforge/arcgis-map @arcgis/core

Basic Usage

<script type="module">
  import '@litforge/arcgis-map';
</script>

<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  basemap="streets-vector"
  zoom="10"
  height="600px"
></arcgis-map>

Using JavaScript Properties

<arcgis-map id="myMap"></arcgis-map>
<script>
  const map = document.getElementById('myMap');
  map.layerIds = ['5a1de28a045f4848b7a5476b1a375dd0'];
  map.center = [-0.0500, 39.9833]; // Castellón de la Plana, Spain
  map.zoom = 10;
</script>

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | portal-url | string | 'https://devgis.waternology.es/portal' | URL of the ArcGIS Portal | | layer-ids | string[] | ['5a1de28a045f4848b7a5476b1a375dd0'] | Array of layer IDs to load from the portal | | basemap | string | 'streets-vector' | Basemap style (streets-vector, satellite, hybrid, topo-vector, etc.) | | center | [number, number] | [-0.0500, 39.9833] | Initial map center coordinates [longitude, latitude] (default: Castellón de la Plana) | | zoom | number | 10 | Initial zoom level (1-20) | | height | string | '100%' | Height of the map container | | width | string | '100%' | Width of the map container | | api-key | string | undefined | ArcGIS API key (optional, for authenticated requests) | | visible-layers | string[] | [] | Array of layer IDs that should be visible. If empty, all layers are visible | | client-layers | ClientLayerConfigUnion[] | [] | Array of client-side layer configurations (GeoJSON, arrays, or CSV) |

Events

| Event | Detail | Description | |-------|--------|-------------| | map-ready | { mapView: MapView, map: Map } | Fired when the map is fully loaded and ready | | map-error | { error: string, originalError: any } | Fired when an error occurs during map initialization | | layer-visibility-change | { layerId: string, visible: boolean } | Fired when a layer's visibility changes | | layer-added | { layerId: string, layer: Layer } | Fired when a new layer is added to the map | | layer-removed | { layerId: string } | Fired when a layer is removed from the map |

Examples

Basic Map with Default Layer

<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
></arcgis-map>

Custom Basemap and Zoom

<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  basemap="satellite"
  zoom="12"
></arcgis-map>

Multiple Layers

<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0", "another-layer-id"]'
></arcgis-map>

Custom Center Coordinates

<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  center='[-0.0500, 39.9833]'
  zoom="12"
></arcgis-map>

Note: The default center is Castellón de la Plana, Comunidad Valenciana, Spain.

With Event Handlers

<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  @map-ready=${(e) => {
    console.log('Map loaded:', e.detail.mapView);
  }}
  @map-error=${(e) => {
    console.error('Map error:', e.detail.error);
  }}
></arcgis-map>

Custom Size

<div style="width: 800px; height: 600px;">
  <arcgis-map
    portal-url="https://devgis.waternology.es/portal"
    layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
    height="600px"
    width="800px"
  ></arcgis-map>
</div>

Layer Visibility Control

Control which layers are visible using the visible-layers attribute:

<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["layer-id-1", "layer-id-2", "layer-id-3"]'
  visible-layers='["layer-id-1", "layer-id-3"]'
></arcgis-map>

Only layer-id-1 and layer-id-3 will be visible. If visible-layers is empty or not provided, all layers are visible by default.

Client-Side Layers

Add layers from your own data sources:

GeoJSON Layer

<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  client-layers='[{
    "id": "custom-points",
    "type": "geojson",
    "title": "Custom Points",
    "visible": true,
    "data": {
      "type": "FeatureCollection",
      "features": [{
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [-0.05, 39.98]
        },
        "properties": {
          "name": "Castellón"
        }
      }]
    }
  }]'
></arcgis-map>

Array Layer

<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  client-layers='[{
    "id": "array-points",
    "type": "array",
    "title": "Array Points",
    "visible": true,
    "geometryType": "point",
    "data": [
      { "lat": 39.98, "lng": -0.05, "name": "Point 1", "value": 10 },
      { "lat": 39.99, "lng": -0.06, "name": "Point 2", "value": 20 }
    ]
  }]'
></arcgis-map>

CSV Layer

<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  client-layers='[{
    "id": "csv-points",
    "type": "csv",
    "title": "CSV Points",
    "visible": true,
    "latField": "lat",
    "lngField": "lng",
    "data": "name,lat,lng,value\nPoint A,39.98,-0.05,100\nPoint B,39.99,-0.06,200"
  }]'
></arcgis-map>

Styling

The component uses CSS variables for theming:

arcgis-map {
  --lf-arcgis-map-min-height: 400px;
  --lf-arcgis-map-font-family: system-ui, Arial, sans-serif;
  --lf-arcgis-map-loading-bg: #f3f4f6;
  --lf-arcgis-map-loading-text: #6b7280;
  --lf-arcgis-map-error-bg: #fee2e2;
  --lf-arcgis-map-error-text: #dc2626;
}

TypeScript

import { ArcGISMap } from '@litforge/arcgis-map';
import type { 
  ArcGISMapProps,
  GeoJSONLayerConfig,
  ArrayLayerConfig,
  CSVLayerConfig 
} from '@litforge/arcgis-map';

const props: ArcGISMapProps = {
  portalUrl: 'https://devgis.waternology.es/portal',
  layerIds: ['5a1de28a045f4848b7a5476b1a375dd0'],
  basemap: 'streets-vector',
  center: [-0.0500, 39.9833], // Castellón de la Plana
  zoom: 10,
  height: '600px',
  width: '100%',
  visibleLayerIds: ['5a1de28a045f4848b7a5476b1a375dd0'],
  clientLayers: [
    {
      id: 'custom-layer',
      type: 'geojson',
      title: 'Custom Layer',
      visible: true,
      data: {
        type: 'FeatureCollection',
        features: []
      }
    } as GeoJSONLayerConfig
  ]
};

Programmatic Access

MapView Access

You can access the MapView instance programmatically:

const mapElement = document.querySelector('arcgis-map') as ArcGISMap;
const mapView = mapElement.getMapView();

if (mapView) {
  // Use MapView API
  mapView.goTo({
    center: [-3.7038, 40.4168],
    zoom: 12
  });
}

Layer Management Methods

Visibility Control

const mapElement = document.querySelector('arcgis-map') as ArcGISMap;

// Show/hide a specific layer
mapElement.setLayerVisible('layer-id', true);
mapElement.setLayerVisible('layer-id', false);

// Get a layer by ID
const layer = mapElement.getLayer('layer-id');

// Get all layers
const allLayers = mapElement.getAllLayers();

// Get only visible layers
const visibleLayers = mapElement.getVisibleLayers();

Adding Client Layers

const mapElement = document.querySelector('arcgis-map') as ArcGISMap;

// Wait for map to be ready
mapElement.addEventListener('map-ready', async () => {
  // Add GeoJSON layer
  await mapElement.addClientLayer({
    id: 'my-geojson-layer',
    type: 'geojson',
    title: 'My GeoJSON Layer',
    visible: true,
    data: {
      type: 'FeatureCollection',
      features: [/* ... */]
    }
  });

  // Add array layer
  await mapElement.addClientLayer({
    id: 'my-array-layer',
    type: 'array',
    title: 'My Array Layer',
    visible: true,
    geometryType: 'point',
    data: [
      { lat: 39.98, lng: -0.05, name: 'Point 1' },
      { lat: 39.99, lng: -0.06, name: 'Point 2' }
    ]
  });

  // Add CSV layer
  await mapElement.addClientLayer({
    id: 'my-csv-layer',
    type: 'csv',
    title: 'My CSV Layer',
    visible: true,
    latField: 'lat',
    lngField: 'lng',
    data: 'name,lat,lng\nPoint A,39.98,-0.05'
  });
});

Removing and Updating Layers

const mapElement = document.querySelector('arcgis-map') as ArcGISMap;

// Remove a client layer
mapElement.removeClientLayer('my-layer-id');

// Update layer properties
await mapElement.updateClientLayer('my-layer-id', {
  visible: false,
  opacity: 0.5,
  title: 'Updated Title'
});

Basemap Options

Available basemap options:

• streets-vector - Street map (default)
• satellite - Satellite imagery
• hybrid - Satellite with labels
• topo-vector - Topographic map
• gray-vector - Light gray canvas
• dark-gray-vector - Dark gray canvas
• oceans - Ocean basemap
• osm - OpenStreetMap

Dependencies

This component requires the ArcGIS Maps SDK for JavaScript:

pnpm add @arcgis/core

The SDK is externalized in the build, so it must be available at runtime. Make sure to include it in your application bundle or load it via CDN.

License

Part of the LitForge component library.