devclassic-map

Interactive, customizable React choropleth map package for Africa, Nigeria, individual States, and LGAs (Local Government Areas) powered by D3-Geo and Framer Motion.

Built for React 18+, Next.js (App & Pages Router), Vite, and modern front-end frameworks.

Components

| Component | Description | |-----------|-------------| | NigeriaMap | National choropleth map of Nigeria with all 36 states + FCT, centroid labels, interactive hover tooltips, and custom value/color bindings. | | StateMap | Single-state boundary choropleth focused and fitted tightly to canvas with score badge and centroid label. | | LGAMap | Local Government Area (LGA) choropleth for any Nigerian state with hover inspection and individual LGA color/score mapping. | | AfricaMap | Pan-African continental choropleth component ready for country-level datasets, with fallback handling when GeoJSON is pending. |

Backward Compatibility: NigeriaStatesChoropleth and StateLGAChoropleth are also exported as direct aliases for NigeriaMap and LGAMap.

Installation

npm install devclassic-map

Or using pnpm / yarn / bun:

pnpm add devclassic-map
# or
yarn add devclassic-map
# or
bun add devclassic-map

Peer Dependencies

Ensure your project has React installed:

npm install react react-dom

Quick Start

1. Nigeria National Map (NigeriaMap)

"use client";

import { NigeriaMap } from "devclassic-map";

const stateScores: Record<string, number> = {
  lagos: 85,
  kano: 68,
  fct: 92,
  rivers: 74,
  kaduna: 62,
};

export default function App() {
  return (
    <div style={{ maxWidth: 800, margin: "0 auto" }}>
      <NigeriaMap
        height={540}
        valueLabel="Score"
        stateValues={stateScores}
        showLabels={true}
        onSelect={(slug, info) => {
          console.log("Selected state:", slug, info);
        }}
      />
    </div>
  );
}

2. Single State Focus (StateMap)

"use client";

import { StateMap } from "devclassic-map";

export function LagosCard() {
  return (
    <StateMap
      stateSlug="lagos"
      stateName="Lagos State"
      value={85}
      valueLabel="Efficiency"
      height={320}
      showLabel={true}
      onClick={(info) => console.log("Clicked:", info)}
    />
  );
}

3. Local Government Area Map (LGAMap)

"use client";

import { LGAMap } from "devclassic-map";

const lgaValues = {
  ikeja: 90,
  epe: 65,
  ikorodu: 72,
  badagry: 58,
};

export function LagosLGAs() {
  return (
    <LGAMap
      stateSlug="lagos"
      stateName="Lagos"
      height={480}
      lgaValues={lgaValues}
      valueLabel="Score"
      onHoverLGA={(lga) => console.log("Hovered LGA:", lga)}
      onSelectLGA={(lga) => console.log("Selected LGA:", lga)}
    />
  );
}

4. Pan-Africa Map (AfricaMap)

AfricaMap is structured and ready for continental datasets. When Africa GeoJSON boundary details are provided (either via geoData in-memory object or geoUrl), it renders the full interactive pan-African choropleth:

"use client";

import { AfricaMap } from "devclassic-map";

export function ContinentalView() {
  return (
    <AfricaMap
      height={560}
      valueLabel="Index"
      countryValues={{
        nga: 75,
        gha: 68,
        ken: 72,
        zaf: 80,
        egy: 65,
      }}
      // Optional: supply GeoJSON via URL or in-memory collection
      // geoUrl="/geo/africa.geo.json"
      // geoData={africaGeoJsonObject}
    />
  );
}

GeoJSON Boundaries

By default, components look for boundary files under your public assets folder:

• Nigeria States: /geo/nigeria-states.geo.json
• Nigeria LGAs: /geo/nigeria-lgas.geo.json

GeoJSON Options:

1. Serve from public folder: Copy the GeoJSON files to your project's public/geo/ directory.
2. Custom URL (geoUrl): Pass any CDN URL or relative path:

   <NigeriaMap geoUrl="https://cdn.example.com/geo/nigeria-states.geo.json" />

3. In-Memory GeoJSON (geoData): Import or load GeoJSON directly into memory and pass it to bypass network fetches:

   import statesGeo from "./data/nigeria-states.json";
   
   <NigeriaMap geoData={statesGeo} />

Props Reference

NigeriaMap Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | stateValues | Record<string, number> | undefined | Map of state slug (e.g. lagos) to score (0–100). | | valueForState | (slug: string) => number | undefined | Function computing score dynamically for each state slug. | | stateColors | Record<string, string> | undefined | Custom fill color overrides per state slug. | | valueLabel | string | "Value" | Label displayed on tooltip. | | geoUrl | string | "/geo/nigeria-states.geo.json" | GeoJSON file URL. | | geoData | NigeriaStateFeatureCollection | undefined | Direct GeoJSON object. | | selectedSlug | string | undefined | Slug of state to highlight with drop-shadow. | | focusStateSlug | string | undefined | Focus canvas to fit only this state. | | showLabels | boolean | false | Display state name at centroid. | | height | number | 540 | Height in pixels. | | defaultFill | string | "#e5e7eb" | Color for states with no value. | | onHover | function | undefined | Callback (slug, info) => void on hover. | | onSelect | function | undefined | Callback (slug, info) => void on click. | | className | string | undefined | Custom wrapper class name. |

StateMap Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | stateSlug | string (required) | — | State slug (e.g. "lagos"). | | stateName | string | undefined | Display name for state. | | value | number | undefined | Score (0–100) mapped to gradient color. | | fillColor | string | undefined | Direct color override. | | geoUrl | string | "/geo/nigeria-states.geo.json" | GeoJSON file URL. | | geoData | NigeriaStateFeatureCollection | undefined | Direct GeoJSON object. | | showLabel | boolean | false | Render state name at centroid. | | height | number | 400 | Height in pixels. | | onHover | function | undefined | Callback (isHovered, info) => void. | | onClick | function | undefined | Callback (info) => void. |

LGAMap Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | stateSlug | string (required) | — | Parent state slug (e.g. "lagos"). | | stateName | string | undefined | State display name. | | lgaValues | Record<string, number> | undefined | Map of slugified LGA name (e.g. ikeja) to score (0–100). | | lgaColors | Record<string, string> | undefined | Map of LGA key to hex/rgb fill color. | | valueForLGA | function | undefined | Fallback function (name, key) => number. | | valueLabel | string | "Value" | Tooltip metric label. | | geoUrl | string | "/geo/nigeria-lgas.geo.json" | GeoJSON file URL. | | geoData | NigeriaLGAFeatureCollection | undefined | Direct GeoJSON object. | | showLabels | boolean | false | Display LGA names at centroid. | | height | number | 520 | Height in pixels. | | onHoverLGA | function | undefined | Callback (lga) => void on LGA hover. | | onSelectLGA | function | undefined | Callback (lga) => void on LGA click. |

Utility Exports

devclassic-map exports utility functions and TypeScript types:

import {
  scoreColor,
  scoreColorScale,
  normalizeStateName,
  slugify,
  lgaKeyFromName,
  stateFeatureSlug,
} from "devclassic-map";

• scoreColor(score: number): string — Converts 0–100 score to green gradient scale.
• normalizeStateName(name: string): string — Normalizes state names (handles "FCT, Abuja", etc.).
• slugify(text: string): string — Converts text to kebab-case slug.
• lgaKeyFromName(name: string): string — Converts LGA name to standardized lookup key.

License

MIT © devclassic