@phila/layerboard

A Vue 3 component framework for building interactive map applications powered by ArcGIS Online WebMaps and MapLibre GL JS. Provide a WebMap ID and get a full mapping app with layer management, popups, legends, search, and more.

Live Examples

• OpenMaps — flat layer list (all layers searchable)
• StreetSmartPHL — topic-based layout (layers grouped in accordions)

Installation

pnpm add @phila/layerboard

Peer Dependencies

pnpm add vue pinia maplibre-gl @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/vue-fontawesome

Quick Start

<template>
  <Layerboard title="My Map App" web-map-id="1596df70df0349e293ceec46a06ccc50" />
</template>

<script setup>
import { Layerboard } from "@phila/layerboard";
import "@phila/layerboard/dist/layerboard.css";
</script>

This renders a full-screen map app with a sidebar listing all layers from the WebMap, complete with legends, opacity sliders, search, popups, and mobile responsiveness.

Layout Modes

Flat Mode (default)

All layers in a searchable list. Set show-default-sidebar to true (default) and the built-in LayerPanel renders in the sidebar.

Topics Mode

Group layers into collapsible accordions using the sidebar slot:

<Layerboard title="StreetSmartPHL" :web-map-id="webMapId" :show-default-sidebar="false">
  <template #sidebar="{ layers, visibleLayers, toggleLayer, setOpacity }">
    <TopicAccordion title="Paving" :expanded="true">
      <LayerCheckboxSet
        :layers="pavingLayers"
        :visible-layer-ids="visibleLayers"
        @toggle-layer="toggleLayer"
        @set-opacity="setOpacity"
      />
    </TopicAccordion>
  </template>
</Layerboard>

Props

| Prop | Type | Default | Description | | ----------------------- | ------------------------------------ | ----------- | --------------------------------------------------- | | title | string | required | App title in header | | webMapId | string | required | ArcGIS Online WebMap ID | | subtitle | string | — | Subtitle in header | | themeColor | string | "#0f4d90" | Header/footer background color | | showDefaultSidebar | boolean | true | Show built-in LayerPanel (false for custom sidebar) | | sidebarWidth | string | "30%" | Sidebar width (CSS units) | | sidebarLabel | string | "Layers" | Mobile toggle label for sidebar view | | mapLabel | string | "Map" | Mobile toggle label for map view | | fetchMetadata | boolean | false | Fetch layer metadata from Carto | | tiledLayers | TiledLayerConfig[] | [] | ESRI MapServer tiled layers | | dataSources | DataSourceConfig[] | [] | External API data sources | | layerStyleOverrides | Record<string, LayerStyleOverride> | {} | Override paint/legend per layer | | popupOverrides | Record<string, PopupOverride> | {} | Override popup behavior per layer | | initialZoom | number | — | Initial map zoom level | | initialCenter | [number, number] | — | Initial map center [lng, lat] | | cyclomediaConfig | CyclomediaConfig | — | Cyclomedia street-level imagery config | | pictometryCredentials | PictometryCredentials | — | Pictometry oblique imagery credentials |

Control Positions

All default to sensible positions. Each accepts "top-left" | "top-right" | "bottom-left" | "bottom-right".

| Prop | Default | | ---------------------------- | ------------------------------------- | | basemapControlPosition | "top-right" | | navigationControlPosition | "bottom-right" | | geolocationControlPosition | "bottom-right" | | searchControlPosition | "top-left" | | drawControlPosition | "bottom-left" (or null to remove) | | cyclomediaButtonPosition | "top-right" | | pictometryButtonPosition | "top-right" |

Events

| Event | Payload | Description | | ---------------- | --------------- | -------------------------------- | | configs-loaded | LayerConfig[] | Layer configs loaded from WebMap | | load-error | string | Error message on load failure | | zoom | number | Zoom level changed |

Slots

| Slot | Scope | Description | | --------- | ---------------------------------------- | -------------------------- | | header | — | Replace default header | | sidebar | layer state + methods (see below) | Replace default LayerPanel | | footer | { openModal, closeModal, isModalOpen } | Custom footer content | | modal | { closeModal } | Modal content |

Sidebar Slot Scope

The sidebar slot exposes the full layer state for building custom UIs:

{
  layers: Array<{ config: LayerConfig; component: string }>
  visibleLayers: Set<string>
  layerOpacities: Record<string, number>
  loadingLayers: Set<string>
  layerErrors: Record<string, string>
  currentZoom: number
  toggleLayer: (id: string) => void
  setLayerVisible: (id: string, visible: boolean) => void
  setLayersVisible: (ids: string[], visible: boolean) => void
  setOpacity: (id: string, opacity: number) => void
  // Tiled layers
  tiledLayers: TiledLayerConfig[]
  visibleTiledLayers: Set<string>
  tiledLayerOpacities: Record<string, number>
  toggleTiledLayer: (id: string) => void
  setTiledLayerVisible: (id: string, visible: boolean) => void
  setTiledLayerOpacity: (id: string, opacity: number) => void
  // Data sources
  dataSourcesState: Record<string, DataSourceState>
  dataSourcesLoading: boolean
  getDataSource: (id: string) => unknown | null
  refetchDataSource: (id: string) => Promise<void>
}

Components

All components are exported for building custom layouts:

import {
  Layerboard, // Main framework component
  LayerPanel, // Flat layer list with search/legends/opacity
  MapPanel, // MapLibre map with layer rendering
  TopicAccordion, // Collapsible accordion for topic grouping
  LayerCheckboxSet, // Checkbox controls for layer toggling
  LayerRadioButtonSet, // Radio buttons for mutually exclusive layers
} from "@phila/layerboard";

Types

All types are exported:

import type {
  LayerConfig,
  LayerDisplayOptions,
  LayerStyleOverride,
  LegendItem,
  PopupConfig,
  PopupField,
  PopupOverride,
  TiledLayerConfig,
  DataSourceConfig,
  DataSourceState,
  LayerboardConfig,
  TopicConfig,
  FeatureFlags,
  CyclomediaConfig, // re-exported from @phila/phila-ui-map-core
  PictometryCredentials, // re-exported from @phila/phila-ui-map-core
} from "@phila/layerboard";

How It Works

1. You provide an ArcGIS Online WebMap ID
2. Layerboard fetches the WebMap JSON at runtime
3. Esri renderers, symbols, scales, and popup configs are transformed into MapLibre-compatible layer configs
4. Layers render on a MapLibre GL map — feature data is fetched from ArcGIS FeatureServer endpoints with spatial filtering and pagination
5. Server-side geometry simplification (maxAllowableOffset) scales with zoom level for polygon layers

Development

pnpm install
pnpm build        # type-check + vite build

Publishing

pnpm version prerelease   # bump beta version
git push origin main
git tag v<version> && git push origin v<version>   # triggers publish workflow