@ttoss/geovis

@ttoss/geovis provides schema-driven geovisualization components for React applications, with a MapLibre engine adapter and a JSON-spec-based runtime.

Installing

pnpm add @ttoss/geovis

You will also need to install MapLibre GL JS as a peer dependency:

pnpm add maplibre-gl

Getting Started

Wrap your application (or a section of it) with GeoVisProvider, passing a VisualizationSpec:

import { GeoVisCanvas, GeoVisProvider } from '@ttoss/geovis';

const spec = {
  id: 'my-map',
  engine: 'maplibre',
  view: { center: [-46.6, -23.5], zoom: 10 },
  sources: [
    {
      id: 'points',
      type: 'geojson',
      data: {
        type: 'FeatureCollection',
        features: [],
      },
    },
  ],
  layers: [
    {
      id: 'points-layer',
      sourceId: 'points',
      geometry: 'point',
    },
  ],
};

const MyMap = () => (
  <GeoVisProvider spec={spec}>
    <GeoVisCanvas viewId="main" style={{ width: '100%', height: '400px' }} />
  </GeoVisProvider>
);

Spec reference

VisualizationSpec

Top-level spec object passed to GeoVisProvider.

| Field | Type | Required | Description | | ------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | id | string | ✓ | Unique spec identifier. | | engine | 'maplibre' | ✓ | Engine adapter to use. Currently only 'maplibre' is supported. | | sources | DataSource[] | ✓ | Data sources referenced by layers. Supported types: 'geojson', 'vector-tiles', 'raster-tiles', 'raster-dem', 'image', 'video'. | | layers | VisualizationLayer[] | ✓ | Ordered list of layers to render (bottom-to-top). | | title | string | | Human-readable title. | | description | string | | Human-readable description. | | view | ViewState | | Initial camera state: center, zoom, pitch, bearing, projection. | | basemap | BaseMapSpec | | Basemap tile style. Pass visible: false to hide tiles and show only GeoJSON layers. | | legends | LegendSpec[] | | Shared legend registry. Layers reference entries via activeLegendId. | | mapData | MapData[] | | Attribute datasets joined to GeoJSON sources for choropleth coloring and tooltips. | | metadata | Record<string, unknown> | | Arbitrary consumer metadata; not read by the runtime. |

VisualizationLayer

Each entry in spec.layers describes one rendered layer.

| Field | Type | Required | Description | | ---------------- | -------------------- | -------- | -------------------------------------------------------------------------------------- | | id | string | ✓ | Unique layer identifier. | | sourceId | string | ✓ | References a DataSource.id from spec.sources. | | geometry | GeoVisGeometryType | ✓ | Render type: 'point', 'line', 'polygon', 'raster', 'symbol', 'heatmap'. | | sourceLayer | string | | Vector tile source layer name. Required when source.type is 'vector-tiles'. | | title | string | | Human-readable layer name. | | visible | boolean | | Whether the layer is rendered. Defaults to true. | | minzoom | number | | Minimum zoom level (0–24) at which the layer is visible. | | maxzoom | number | | Maximum zoom level (0–24) at which the layer is visible. | | paint | LayerPaint | | Per-geometry paint properties. See examples below. | | legends | LegendSpec[] | | Alternative legend definitions exposed as runtime toggles. | | activeLegendId | string | | Active entry from legends[]. Enables choropleth coloring and the hover tooltip. | | mapDataId | string | | References a MapData.mapDataId for per-feature value joining (choropleth / tooltip). |

Paint properties

The paint field accepts different shapes depending on geometry. The three most common:

Polygon (geometry: 'polygon') — FillPaint

paint: {
  fillColor: '#3b82f6',   // fill-color
  fillOpacity: 0.6,       // fill-opacity
  lineColor: '#1d4ed8',   // outline color (fill-outline-color)
}

Line (geometry: 'line') — LinePaint

paint: {
  lineColor: '#ef4444',   // line-color
  lineWidth: 2,           // line-width (pixels)
  lineOpacity: 0.8,       // line-opacity
}

Point (geometry: 'point') — CirclePaint

paint: {
  circleColor: '#10b981',       // circle-color
  circleRadius: 6,              // circle-radius (pixels)
  circleStrokeColor: '#065f46', // circle-stroke-color
  circleStrokeWidth: 1,         // circle-stroke-width (pixels)
}

Data-driven maps

mapData decouples attribute values from geometry: the GeoJSON source holds shapes while mapData holds per-feature values. The adapter joins them at runtime via setFeatureState, enabling choropleth coloring and hover tooltips without modifying source features.

Choropleth example

Declare mapData in the spec, reference it on the layer with mapDataId, and connect a legend via activeLegendId.

import {
  GeoVisCanvas,
  GeoVisHoverTooltip,
  GeoVisLegend,
  GeoVisProvider,
} from '@ttoss/geovis';
import districtsGeoJSON from './districts.geojson';

const spec = {
  id: 'population-map',
  engine: 'maplibre',
  view: { center: [-46.6, -23.5], zoom: 10 },
  sources: [{ id: 'districts', type: 'geojson', data: districtsGeoJSON }],
  mapData: [
    {
      mapDataId: 'population',
      mapId: 'districts', // references sources[].id
      // joinKey: 'cd_district' — set when features lack a numeric .id
      data: [
        { geometryId: 1, value: 87_000 },
        { geometryId: 2, value: 143_000 },
        { geometryId: 3, value: 210_000 },
      ],
    },
  ],
  legends: [
    {
      id: 'population-legend',
      label: 'Population',
      colorBy: {
        type: 'quantitative',
        property: 'value',
        scale: 'threshold',
        thresholds: [100_000, 200_000],
        colors: ['#bfdbfe', '#3b82f6', '#1d4ed8'],
        defaultColor: '#e2e8f0', // features with no joined value
      },
    },
  ],
  layers: [
    {
      id: 'districts-layer',
      sourceId: 'districts',
      geometry: 'polygon',
      mapDataId: 'population', // drives setFeatureState
      activeLegendId: 'population-legend', // enables coloring + hover
    },
  ],
};

const PopulationMap = () => (
  <GeoVisProvider spec={spec}>
    <div style={{ width: '100%', height: '500px' }}>
      <GeoVisCanvas viewId="main" style={{ width: '100%', height: '100%' }} />
    </div>
    {/* GeoVisHoverTooltip can be placed anywhere in the tree — */}
    {/* it uses position:fixed and viewport coordinates internally. */}
    <GeoVisHoverTooltip />
    <GeoVisLegend legendId="population-legend" />
  </GeoVisProvider>
);

Joining by property instead of feature id

When GeoJSON features do not have a numeric or string .id, use joinKey to match by a feature property instead:

mapData: [
  {
    mapDataId: 'population',
    mapId: 'districts',
    joinKey: 'cd_district', // matches feature.properties.cd_district
    data: [
      { geometryId: 'CAMPO_LIMPO', value: 143_000 },
      { geometryId: 'BUTANTA',     value: 87_000 },
    ],
  },
],

Accessing data in React

useMapData exposes the joined dataset in React without touching MapLibre:

import { useMapData } from '@ttoss/geovis';

const DataTable = () => {
  const result = useMapData('population');
  if (!result) return null;
  const { rows } = result;
  return (
    <ul>
      {rows.map((row) => (
        <li key={row.geometryId}>
          {row.geometryId}: {row.value}
        </li>
      ))}
    </ul>
  );
};

Must be called inside GeoVisProvider.

Updating data at runtime

Use applyPatch with target: 'mapData' to replace the full dataset or upsert a single row without re-mounting the spec:

const { applyPatch } = useGeoVis();

// Replace the full dataset — value must be a complete MapData object
applyPatch({
  target: 'mapData',
  op: 'replace',
  path: 'mapData.population',
  value: { mapDataId: 'population', mapId: 'states-source', data: newRows }, // MapData
});

// Upsert a single row — path: 'mapData.<mapDataId>.data.<geometryId>'
applyPatch({
  target: 'mapData',
  op: 'replace',
  path: 'mapData.population.data.1',
  value: 210_000,
});

Spec Validation

Use validateSpec to validate a visualization spec against the JSON schema before passing it to GeoVisProvider:

import { validateSpec } from '@ttoss/geovis';

const result = validateSpec(rawSpec);

if (!result.valid) {
  console.error('Invalid spec:', result.errors);
} else {
  // result.spec is fully typed as VisualizationSpec
}

Applying Patches

Use useGeoVis to access applyPatch for efficient updates without re-rendering the full spec.

Supported target values:

| Target | Description | | ----------- | ------------------------------------------ | | 'layer' | Add, remove, or update a layer | | 'source' | Add, remove, or update a source | | 'mapData' | Update feature-state data bound to the map |

Note: view and style changes must be applied via update(spec) (full spec replacement), not via applyPatch.

A SpecPatch has the shape:

type SpecPatch =
  | {
      target: 'layer' | 'source' | 'mapData';
      op: 'replace';
      path: string; // dot-separated: "layer.<layerId>.paint.<camelCaseKey>"
      //                "mapData.<mapDataId>"
      //                "mapData.<mapDataId>.data.<geometryId>"
      value?: unknown; // required for 'replace'
      rationale?: string;
    }
  | {
      target: 'layer' | 'source' | 'mapData';
      op: 'add' | 'remove';
      path?: string; // unused for layer/source add and remove ops
      value?: unknown;
      rationale?: string;
    };

Paint property keys follow spec-level camelCase (e.g. circleOpacity, fillColor, lineWidth).

replace — update an existing paint property

The most common operation. Updates a single paint property on a live layer without re-mounting the map.

const { applyPatch } = useGeoVis();

// Change the opacity of a circle layer via a range slider
applyPatch({
  target: 'layer',
  op: 'replace',
  path: 'layer.points-layer.paint.circleOpacity',
  value: 0.5,
});

// Change the fill color of a polygon layer
applyPatch({
  target: 'layer',
  op: 'replace',
  path: 'layer.regions-layer.paint.fillColor',
  value: '#ff0000',
});

Effect: the adapter calls setPaintProperty on the live map without re-mounting — runtime.spec is updated and effectiveSpec in context is refreshed, triggering a lightweight re-render in consumers but no map re-mount.

add — add a new layer or source to the spec

Use add to append a new VisualizationLayer or DataSource at runtime.

applyPatch({
  target: 'layer',
  op: 'add',
  value: { id: 'new-layer', sourceId: 'points', geometry: 'point' },
});

applyPatch({
  target: 'source',
  op: 'add',
  value: {
    id: 'new-source',
    type: 'geojson',
    data: { type: 'FeatureCollection', features: [] },
  },
});

Effect: the layer or source is appended to runtime.spec and forwarded to the adapter. No React re-render triggered.

remove — remove a layer or source from the spec

Pass the target id as value to remove an existing layer or source.

applyPatch({
  target: 'layer',
  op: 'remove',
  value: 'routes-layer', // id of the layer to remove
});

applyPatch({
  target: 'source',
  op: 'remove',
  value: 'routes-source', // id of the source to remove
});

Effect: the entry is removed from runtime.spec and the adapter is notified.

Full interactive example

import { useGeoVis } from '@ttoss/geovis';

const LayerControls = () => {
  const { applyPatch } = useGeoVis();

  return (
    <>
      <label>
        Opacity
        <input
          type="range"
          min={0}
          max={1}
          step={0.1}
          defaultValue={1}
          onChange={(e) =>
            applyPatch({
              target: 'layer',
              op: 'replace',
              path: 'layer.points-layer.paint.circleOpacity',
              value: Number(e.target.value),
            })
          }
        />
      </label>
      <button
        onClick={() =>
          applyPatch({
            target: 'layer',
            op: 'replace',
            path: 'layer.points-layer.paint.circleStrokeColor',
            value: '#ffffff',
          })
        }
      >
        Add stroke
      </button>
      <button
        onClick={() =>
          applyPatch({
            target: 'layer',
            op: 'replace',
            path: 'layer.points-layer.paint.circleStrokeColor',
            value: undefined, // undefined is treated as a no-op — use op:'remove' to remove a paint property
          })
        }
      >
        Remove stroke
      </button>
    </>
  );
};

API

GeoVisProvider

Provides a GeoVis runtime context for child components. Resolves the appropriate engine adapter based on spec.engine, initializes the runtime, and keeps it in sync with spec updates.

| Prop | Type | Description | | ---------- | ------------------- | --------------------------------------------------------------------------- | | spec | VisualizationSpec | The visualization spec (memoize with useMemo to avoid redundant updates). | | children | React.ReactNode | Child components, typically GeoVisCanvas. |

Error handling: if the engine adapter throws during initialization, GeoVisProvider re-throws the error. Wrap it with an <ErrorBoundary> to catch adapter errors and display a fallback UI instead of a blank screen.

<ErrorBoundary fallback={<p>Map failed to load.</p>}>
  <GeoVisProvider spec={spec}>
    <GeoVisCanvas viewId="main" style={{ width: '100%', height: '400px' }} />
  </GeoVisProvider>
</ErrorBoundary>

GeoVisCanvas

Renders the map inside a div container mounted by the active engine. Must be used inside GeoVisProvider.

| Prop | Type | Description | | ----------- | --------------------- | -------------------------------------------------- | | viewId | string | Unique identifier for this canvas view. | | style | React.CSSProperties | Optional inline styles for the container element. | | className | string | Optional CSS class name for the container element. |

useGeoVis

Returns the current GeoVisContextValue. Must be called inside GeoVisProvider.

| Return value | Type | Description | | ------------------ | ----------------------------------- | -------------------------------------------------------------------------------------------------------------- | | spec | VisualizationSpec | Current effective spec (updated after each applyPatch). | | applyPatch | (patch: SpecPatch) => void | Dispatch a patch without re-mounting the map. | | setView | (options: SetViewOptions) => void | Imperatively move the camera (center, zoom, pitch, bearing). | | policyViolations | PolicyViolation[] | Active policy violations derived from the current spec. Each entry has reason: string and message: string. | | runtime | GeoVisRuntime \| null | Low-level runtime instance. Avoid direct access in app code. |

SetViewOptions fields: center?: LngLat, zoom?: number, pitch?: number, bearing?: number, animate?: boolean (defaults true — smooth flyTo).

const { setView } = useGeoVis();

// Fly to a new center/zoom
setView({ center: [-46.6, -23.5], zoom: 12 });

// Instant jump (no animation)
setView({ center: [-43.1, -22.9], zoom: 10, animate: false });

Before the map has mounted, setView has no effect on the rendered map but still updates spec.view in the runtime. The camera will not move until a view is mounted.

useGeoVisHover

Returns the live MapHoverInfo | null snapshot for the feature currently hovered on a polygon layer with activeLegendId. Lives in a dedicated context so high-frequency hover updates do not re-render useGeoVis() consumers. Must be called inside GeoVisProvider.

useGeoVisClick

Returns the last clicked feature on the active map as MapClickInfo | null (null when no feature is selected). Unlike hover state, click state persists until dismissed — it clears to null when the user presses Escape or clicks outside a tracked layer/feature.

Tracking: useGeoVisClick only populates when the user clicks a feature on a layer configured with activeLegendId and the feature has an id (numeric or string). Clicks on untracked layers or features without ids are treated as outside-clicks and clear the selection.

Lives in a dedicated context (GeoVisClickContext) so click-state changes do not re-render useGeoVis() consumers. Must be called inside GeoVisProvider.

MapClickInfo fields

| Field | Type | Description | | ----------- | -------------------------- | ------------------------------------------------------------------------------ | | layerId | string | Layer id that received the click. | | sourceId | string | Source id backing the layer. | | featureId | string \| number | Clicked feature's id (typically geometryId from mapData). | | value | number \| string \| null | feature-state.value at click time; same semantics as MapHoverInfo.value. | | lngLat | [number, number] | Geographic coordinates [lng, lat] of the click. Useful for anchoring popups. | | point | { x: number; y: number } | Canvas-relative pixel coordinates of the click. |

Example — center map on clicked feature

import { useGeoVis, useGeoVisClick } from '@ttoss/geovis';
import { useEffect } from 'react';

const CenterOnClick = () => {
  const { setView } = useGeoVis();
  const click = useGeoVisClick();

  useEffect(() => {
    if (click) {
      setView({ center: click.lngLat, zoom: 14 });
    }
  }, [click, setView]);

  return null;
};

// Place <CenterOnClick /> anywhere inside <GeoVisProvider>

useMapData

Returns indexed map data for a mapDataId as { mapDataId, mapId, joinKey, values, rows }. Must be called inside GeoVisProvider.

GeoVisLegend

Renders a static, non-interactive legend resolved from the active spec. Resolution looks up legendId in spec.legends first, then in each layer.legends. Categorical legends emit one swatch per mapping entry (or a single fallback swatch when mapping is empty, mirroring the adapter's ['literal', fallbackColor] paint output). Quantitative legends emit one swatch per breaks[] bin and use the same fallback chain as the adapter (defaultColor ?? palette[0] ?? DEFAULT_MISSING_COLOR). Must be rendered inside GeoVisProvider.

| Prop | Type | Description | | ------------- | --------------------------- | --------------------------------------------------------------------- | | legendId | string | Id of the legend entry to render. | | breaks | number[] | Externally computed thresholds for quantitative legends. Optional. | | formatValue | (value: number) => string | Formatter for quantitative break labels. Defaults to String(value). | | className | string | Optional CSS class for the legend container. |

GeoVisHoverTooltip

Renders a floating tooltip over the map whenever the user hovers a polygon feature on a layer that has an activeLegendId. Uses position: fixed and viewport-relative coordinates internally, so it can be placed anywhere in the React tree — no shared container with <GeoVisCanvas> required. Internally subscribes to GeoVisHoverContext via useGeoVisHover(), so high-frequency hover updates do not re-render useGeoVis() consumers.

| Prop | Type | Description | | ----------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------ | | render | (info: MapHoverInfo) => React.ReactNode | Custom tooltip renderer. When omitted, a default two-line layout is used. | | formatValue | (value: number \| string) => string | Formatter applied to info.value when no render prop is provided. | | className | string | Optional CSS class for the tooltip container. | | style | React.CSSProperties | Optional inline style overrides merged on top of the default tooltip style. | | offset | { x: number; y: number } | Pixel offset from the cursor. Defaults to { x: 12, y: 12 }. | | emptyValueLabel | string | Label shown when info.value is null (no mapData for the feature). Defaults to 'No data'. |

validateSpec

Validates a plain object against the @ttoss/geovis JSON schema.

Returns { valid: true, spec: VisualizationSpec } or { valid: false, errors: string[] }.

Legend Type Surface

VisualizationLayer exposes optional legends and activeLegendId fields, and VisualizationSpec exposes optional legends for shared legend registries. colorBy lives on LegendSpec (not on the layer), and the color and legend types are part of the public spec/types contract, so consumers can type legend-aware specs without reaching into internal files.

For more on product development principles that guide our approach, see Product Development Principles.