carbonmapper-iraq-widget

A self-contained React widget for visualizing methane (CH4) and CO2 emission plumes across Iraq, powered by the Carbon Mapper API and Mapbox GL.

Features

• Interactive Mapbox map with light basemap and plume markers color-coded by emission rate
• Filter sidebar: pollutant type, date range, emission rate (dual-thumb slider, 0-500k kg/hr), governorate
• Key Insights panel with top-emitting governorates ranked by total emission
• Click a plume to view province-level historical data, emission chart, and plume image overlay
• Fully typed TypeScript exports

Installation

npm install carbonmapper-iraq-widget mapbox-gl

Quick Start

import { CarbonMapperWidget } from 'carbonmapper-iraq-widget';
import 'carbonmapper-iraq-widget/styles';
import 'mapbox-gl/dist/mapbox-gl.css';

export default function Page() {
  return (
    <div style={{ height: '100vh' }}>
      <CarbonMapperWidget
        apiKey="YOUR_CARBONMAPPER_API_KEY"
        mapboxToken="YOUR_MAPBOX_TOKEN"
      />
    </div>
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiKey | string | NEXT_PUBLIC_CARBONMAPPER_API_KEY env var | Carbon Mapper API bearer token | | mapboxToken | string | NEXT_PUBLIC_MAPBOX_TOKEN env var | Mapbox GL access token |

Exports

import {
  CarbonMapperWidget,  // Main widget component
  DEFAULT_FILTERS,     // Default filter state
  THEME,               // Theme color constants
  IRAQ_GOVERNORATES,   // List of Iraqi governorates
} from 'carbonmapper-iraq-widget';

import type {
  Filters,             // Filter state type
  PlumeAnnotated,      // Plume data type
} from 'carbonmapper-iraq-widget';

Styles

The widget requires two CSS imports:

1. Widget styles — carbonmapper-iraq-widget/styles (sidebar, slider, popups, scrollbar)
2. Mapbox GL CSS — mapbox-gl/dist/mapbox-gl.css (map rendering)

If you use Tailwind CSS, the widget's utility classes will work automatically. The widget scopes its dark-blue theme to its own container so it won't affect your app's styles.

Usage with Next.js App Router

// app/dashboard/page.tsx
import { CarbonMapperWidget } from 'carbonmapper-iraq-widget';
import 'carbonmapper-iraq-widget/styles';
import 'mapbox-gl/dist/mapbox-gl.css';

export default function Dashboard() {
  return (
    <div className="h-[600px] rounded-lg overflow-hidden">
      <CarbonMapperWidget
        apiKey={process.env.NEXT_PUBLIC_CARBONMAPPER_API_KEY}
        mapboxToken={process.env.NEXT_PUBLIC_MAPBOX_TOKEN}
      />
    </div>
  );
}

Usage via iframe

If you prefer not to install the package, deploy this project and embed it:

<iframe
  src="https://your-deployment.vercel.app/embed"
  width="100%"
  height="600"
  style="border: none; border-radius: 8px;"
></iframe>

Development

# Run the demo app locally
npm run dev

# Build the npm package
npm run build:lib

# Build the Next.js app
npm run build

Theme

The widget uses a dark blue + green accent theme:

| Token | Color | Usage | |-------|-------|-------| | cardBg | #1C345C | Sidebar/panel backgrounds | | cardBorder | #3D5A9E | Borders | | accent | #92D050 | Interactive elements, highlights | | ch4Color | #FF6B35 | Methane plume markers | | co2Color | #4DA8DA | CO2 plume markers |

Requirements

• React 18+
• A Carbon Mapper API key
• A Mapbox access token

License

MIT