MapLibre GL National Map

A MapLibre GL JS plugin for searching and adding USGS National Map web services to a map. It ships as a standard MapLibre IControl with a React wrapper, and also builds as a GeoLibre Desktop plugin bundle.

Features

• Service Catalog - Browse 20+ USGS National Map services grouped by collapsible categories (Basemaps, Hydrography, Elevation, Cartography, Indexes)
• Search - Filter services by name, title, description, or category; matching categories expand automatically
• Layer Insertion Point - An "Insert before" selector in the panel (or the beforeId option) inserts added layers beneath an existing layer (e.g. labels); changing it re-anchors layers already added
• Resizable Panel - Drag the panel edge to resize; works from left and right corner placements
• Live Catalog Refresh - Fetches the latest service listings from the National Map ArcGIS REST endpoints at runtime, with a built-in static catalog as an instant-render fallback (works offline)
• Layer Management - Toggle visibility, adjust opacity, and remove added layers from an "Active layers" section
• Light/Dark Theme - Follows prefers-color-scheme by default, with a theme option to force light or dark
• Small-Screen Friendly - The panel constrains itself to the map height and scrolls vertically
• Collapsible Control - 29x29 toggle button matching MapLibre's navigation control, with a floating panel
• TypeScript Support - All public types exported from the package root
• React Integration - React wrapper component and custom hook
• GeoLibre Bundle Output - Builds a zip with root plugin.json, bundled ESM, and CSS for GeoLibre Desktop

Supported Services

The catalog mirrors the map services listed at apps.nationalmap.gov/services. All endpoints are CORS-enabled ArcGIS REST services and need no API key:

Category	Services	Rendering
Basemaps	USGS Topo, Imagery Only, Imagery Topo, Shaded Relief, Hydro Cached	Cached XYZ tiles
Hydrography	3DHP, NHD, NHDPlus HR, Watershed Boundary Dataset	Dynamic map export
Elevation	3DEP Elevation (hillshade)	ImageServer export
Imagery	NAIP Plus, NAIP False Color Imagery, NAIP NDVI	ImageServer export
Cartography	Contours, Geographic Names, Governmental Units, Map Indices, Selectable Polygons, Structures, Transportation, USGS Trails	Dynamic map export
Hazards	FEMA National Flood Hazard Layer	Dynamic map export
Other Data	Scanned USA Topo Maps, BLM PLSS, FWS National Wetlands Inventory	Cached tiles / map export
Indexes	3DEP Elevation Index, NHDPlus HR Index, Seamless 1m DEM Index, NAIP Imagery Index, US Topo Availability, Special Edition 250K Maps, 3DEP Acquisition Grid	Dynamic map export

A few services from the page are intentionally excluded: WFS/WCS endpoints and FeatureServers (not raster-displayable), NLCD land cover (WMS landing page only), and partner endpoints that were unreachable at testing time (ScienceBase geology, USGS ecosystems, GAP land cover, earthquake faults, mine symbols, NPS boundaries).

Note: layers added later render on top of earlier ones (or beneath the beforeId layer when configured). Remove and re-add layers to change stacking.

Installation

npm install maplibre-gl-national-map

Quick Start

Vanilla JavaScript/TypeScript

import maplibregl from "maplibre-gl";
import { NationalMapControl } from "maplibre-gl-national-map";
import "maplibre-gl-national-map/style.css";

const map = new maplibregl.Map({
  container: "map",
  style: "https://tiles.openfreemap.org/styles/positron",
  center: [-98.5, 39.8],
  zoom: 4,
});

map.on("load", () => {
  const control = new NationalMapControl({
    title: "USGS National Map",
    collapsed: false,
    theme: "auto",
  });

  map.addControl(control, "top-right");

  // Programmatic layer management
  control.addService("basemap/USGSTopo");
  console.log(control.getActiveLayers());
});

React

import { useEffect, useRef, useState } from "react";
import maplibregl, { Map } from "maplibre-gl";
import {
  NationalMapControlReact,
  useNationalMapState,
} from "maplibre-gl-national-map/react";
import "maplibre-gl-national-map/style.css";

function App() {
  const mapContainer = useRef<HTMLDivElement>(null);
  const [map, setMap] = useState<Map | null>(null);
  const { state, toggle } = useNationalMapState();

  useEffect(() => {
    if (!mapContainer.current) return;

    const mapInstance = new maplibregl.Map({
      container: mapContainer.current,
      style: "https://tiles.openfreemap.org/styles/positron",
      center: [-98.5, 39.8],
      zoom: 4,
    });

    mapInstance.on("load", () => setMap(mapInstance));

    return () => mapInstance.remove();
  }, []);

  return (
    <div style={{ width: "100%", height: "100vh" }}>
      <div ref={mapContainer} style={{ width: "100%", height: "100%" }} />
      {map && (
        <NationalMapControlReact
          map={map}
          title="National Map"
          collapsed={state.collapsed}
          theme="auto"
          onStateChange={(newState) => console.log(newState)}
        />
      )}
    </div>
  );
}

API

NationalMapControl

The main control class implementing MapLibre's IControl interface.

Constructor Options

Option	Type	Default	Description
collapsed	boolean	true	Whether the panel starts collapsed (showing only the 29x29 toggle button)
position	string	'top-right'	Control position on the map
title	string	'USGS National Map'	Title displayed in the header
panelWidth	number	320	Initial width of the dropdown panel in pixels (user-resizable by dragging the panel edge)
className	string	''	Custom CSS class name
theme	string	'auto'	Color theme: 'light', 'dark', or 'auto' (follows prefers-color-scheme)
beforeId	string	undefined	Existing layer id to insert added layers before, so services render underneath it (ignored if the layer does not exist). Also adjustable at runtime via the panel's "Insert before" selector

Methods

• toggle() - Toggle the collapsed state
• expand() - Expand the panel
• collapse() - Collapse the panel
• getState() - Get the current state (includes activeLayerIds)
• setState(state) - Update the state
• addService(serviceId) - Add a catalog service to the map (e.g. "basemap/USGSTopo")
• removeService(serviceId) - Remove a previously added service
• setServiceOpacity(serviceId, opacity) - Set the opacity (0–1) of an active service
• setServiceVisibility(serviceId, visible) - Show or hide an active service
• getActiveLayers() - Get the services currently added to the map
• setTheme(theme) - Change the theme at runtime
• on(event, handler) - Register an event handler
• off(event, handler) - Remove an event handler
• getMap() - Get the map instance
• getContainer() - Get the container element

Events

• collapse - Fired when the panel is collapsed
• expand - Fired when the panel is expanded
• statechange - Fired when the state changes
• layeradd - Fired when a service is added to the map (event.service is the service)
• layerremove - Fired when a service is removed from the map

NationalMapControlReact

React wrapper component for NationalMapControl.

Props

All NationalMapControl options plus:

Prop	Type	Description
map	Map	MapLibre GL map instance (required)
onStateChange	function	Callback fired when state changes

useNationalMapState

Custom React hook for managing control state.

const {
  state, // Current state
  setState, // Replace the state
  setCollapsed, // Set collapsed state
  setPanelWidth, // Set panel width
  setData, // Merge custom data
  reset, // Reset to defaults
  toggle, // Toggle collapsed
} = useNationalMapState({ collapsed: false });

Data Layer

The catalog and spec builders are exported for advanced use without the UI control:

import {
  STATIC_CATALOG, // Built-in service catalog
  fetchCatalog, // Live catalog fetch with static fallback
  buildLayerSpec, // NationalMapService -> MapLibre source/layer specs
  filterServices, // Search the catalog
  groupByCategory, // Group services for display
  LayerManager, // Add/remove/visibility/opacity on a map
} from "maplibre-gl-national-map";

const spec = buildLayerSpec(STATIC_CATALOG[0]);
map.addSource(spec.sourceId, spec.source);
map.addLayer(spec.layer);

Exported types include NationalMapService, NationalMapControlOptions, NationalMapState, NationalMapTheme, NationalMapHost, NationalMapCategory, ServiceType, ServiceRenderMode, ActiveLayer, LayerSpec, and CategoryGroup.

Theming

The control uses CSS custom properties scoped to .national-map and .national-map-panel. With theme: 'auto' (default), dark colors apply when the OS is in dark mode. Use theme: 'light' or theme: 'dark' to force a theme, or override the --nm-* variables in your own CSS:

.national-map-panel {
  --nm-accent: #2e7d32;
  --nm-accent-hover: #1b5e20;
}

Examples

Run locally:

npm install
npm run dev

• Basic: http://localhost:5173/examples/basic/
• React (with theme switcher): http://localhost:5173/examples/react/

Build a GeoLibre plugin zip

GeoLibre Desktop loads external plugins from an app data plugins/ directory. The zip must contain plugin.json at the root, plus a bundled ESM entry and optional CSS file.

npm install
npm run package:geolibre

This creates:

geolibre-plugin/maplibre-gl-national-map-0.1.0.zip

Copy the zip into GeoLibre Desktop's app data plugins/ directory and restart GeoLibre. On Linux with the default app identifier, that directory is usually:

~/.local/share/org.geolibre.desktop/plugins/

For the GeoLibre web app, serve the unpacked plugin with CORS enabled:

npm run package:geolibre
npm run serve:geolibre -- 8000

Then add this manifest URL in GeoLibre Settings > Plugins:

http://localhost:8000/plugin.json

Development

npm install      # Install dependencies
npm run dev      # Start the dev server
npm test         # Run the test suite
npm run lint     # Lint
npm run build    # Build the library and GeoLibre bundle

Docker

docker build -t maplibre-gl-national-map .
docker run -p 8080:80 maplibre-gl-national-map
# Open http://localhost:8080/maplibre-gl-national-map/

License

MIT