Superset Legacy Plugin Chart Country Map

A legacy country map visualization plugin for Apache Superset that creates interactive choropleth-style maps for displaying geographical data across various countries and regions. This plugin enables users to visualize metrics across a country's principal subdivisions (states, provinces, etc.) with hover interactions and zoom capabilities.

Package Information

• Package Name: @superset-ui/legacy-plugin-chart-country-map
• Package Type: npm
• Language: JavaScript/TypeScript
• Installation: npm install @superset-ui/legacy-plugin-chart-country-map

Core Imports

import CountryMapChartPlugin, { countries } from "@superset-ui/legacy-plugin-chart-country-map";

For CommonJS:

const CountryMapChartPlugin = require("@superset-ui/legacy-plugin-chart-country-map").default;
const { countries } = require("@superset-ui/legacy-plugin-chart-country-map");

Basic Usage

import CountryMapChartPlugin from "@superset-ui/legacy-plugin-chart-country-map";

// Register the plugin with Superset
const plugin = new CountryMapChartPlugin();

// Access country mappings for configuration
import { countries } from "@superset-ui/legacy-plugin-chart-country-map";
console.log(countries.usa); // Returns USA GeoJSON data path
// For country options, you need to import directly from countries module
// or access via separate import since it's not re-exported from main index

Architecture

The plugin follows Superset's chart plugin architecture:

• Chart Plugin Class: Main CountryMapChartPlugin that extends Superset's ChartPlugin base class
• Chart Component: D3-based visualization component (CountryMap) wrapped in React (ReactCountryMap)
• Data Transformation: transformProps function that converts Superset data format to chart props
• Control Panel: Configuration interface defining available chart options
• Country Data: Pre-loaded GeoJSON data for 62+ countries and regions

Capabilities

Chart Plugin Registration

Main plugin class for registering the country map visualization with Superset.

/**
 * Main chart plugin class for country map visualization
 * Extends ChartPlugin from @superset-ui/core
 */
class CountryMapChartPlugin extends ChartPlugin {
  constructor();
}

export default CountryMapChartPlugin;

Country Data Access

Access to country mappings and configuration options for building country selection interfaces.

/**
 * Country mappings object - contains imported GeoJSON data for each supported country
 * This is the countries object from countries.ts, re-exported as named export
 */
export const countries: Record<string, any>;

Additional Utilities

For advanced usage, the countries module also exports additional utilities that are not re-exported from the main index:

/**
 * Array of [value, label] pairs for UI select controls
 * Available as named export from '@superset-ui/legacy-plugin-chart-country-map/lib/countries'
 * Generated from country keys with proper capitalization
 */
export const countryOptions: Array<[string, string]>;

Chart Component Interface

The core chart component props interface (used internally by the plugin). Note: The actual implementation uses JavaScript with PropTypes validation, not TypeScript.

/**
 * Props interface for the CountryMap component (based on PropTypes)
 */
interface CountryMapProps {
  /** Visualization data with country IDs and metrics */
  data: Array<{
    country_id: string;
    metric: number;
  }>;
  /** Chart width in pixels */
  width: number;
  /** Chart height in pixels */
  height: number;
  /** Country identifier for map selection */
  country: string;
  /** Color scheme identifier for linear scaling */
  linearColorScheme: string;
  /** Number formatting specification */
  numberFormat: string;
  /** Base URL for map data (optional) */
  mapBaseUrl?: string;
}

Props Transformation

Transform function that converts Superset chart properties to component props.

/**
 * Transforms Superset chart properties to CountryMap component props
 * @param chartProps - Raw chart properties from Superset
 * @returns Transformed props for CountryMap component
 */
function transformProps(chartProps: ChartPropsConfig): CountryMapProps;

interface ChartPropsConfig {
  width: number;
  height: number;
  formData: {
    linearColorScheme: string;
    numberFormat: string;
    selectCountry: string;
    colorScheme?: string;
    sliceId?: string;
  };
  queriesData: Array<{
    data: Array<{
      country_id: string;
      metric: number;
    }>;
  }>;
}

Control Panel Configuration

Control panel configuration for chart customization in Superset UI.

/**
 * Control panel configuration object for Superset UI
 */
interface ControlPanelConfig {
  controlPanelSections: Array<ControlSection>;
  controlOverrides: Record<string, ControlOverride>;
}

interface ControlSection {
  label: string;
  expanded: boolean;
  controlSetRows: Array<Array<string | ControlConfig>>;
  tabOverride?: string;
}

interface ControlConfig {
  name: string;
  config: {
    type: string;
    label: string;
    default?: any;
    choices?: Array<[string, string]>;
    description: string;
    validators?: Array<Function>;
    renderTrigger?: boolean;
    freeForm?: boolean;
  };
}

const controlPanel: ControlPanelConfig;
// Note: controlPanel is used internally by the plugin but not exported from main index

Supported Countries

The plugin includes GeoJSON data for 62+ countries and regions:

• Major Countries: USA, China, India, Brazil, Germany, France, UK, Japan, Italy, Spain, Canada, Australia, Russia, etc.
• European Countries: Austria, Belgium, Bulgaria, Cyprus, Denmark, Estonia, Finland, Iceland, Lithuania, Netherlands, Norway, Poland, Portugal, Slovenia, Sweden, Switzerland, Ukraine
• Asian Countries: Indonesia, Iran, Jordan, Korea, Kuwait, Malaysia, Myanmar, Pakistan, Philippines, Singapore, Thailand, Vietnam
• African Countries: Egypt, Ethiopia, Kenya, Morocco, Nigeria, Rwanda, Tanzania, Uganda, Zambia, Burundi
• Other Regions: Mexico, Peru, Uruguay, Qatar, Saudi Arabia, United Arab Emirates, Oman, Syria, Liechtenstein, Timor-Leste
• Special Regions: Italy (regions) - separate regional view for Italy

Chart Metadata

The plugin registers with the following metadata:

• Category: Map
• Name: Country Map
• Description: Visualizes how a single metric varies across a country's principal subdivisions on a choropleth map
• Tags: 2D, Comparison, Geo, Range, Report, Stacked
• Legacy API: Uses Superset's legacy API (useLegacyApi: true)

Data Format

Input data should be formatted as an array of objects with:

interface ChartDataPoint {
  /** ISO 3166-2 code for the region/subdivision */
  country_id: string;
  /** Numeric value to visualize */
  metric: number;
}

Dependencies

Runtime Dependencies

• d3@^3.5.17 - D3.js library for data visualization
• d3-array@^2.0.3 - D3 array utilities for data processing
• prop-types@^15.6.2 - React prop types validation

Peer Dependencies

• @superset-ui/chart-controls@* - Superset chart control components
• @superset-ui/core@* - Superset core utilities and base classes

Features

• Interactive Choropleth Maps: Color-coded regions based on metric values
• Hover Interactions: Display region names and values on mouse hover
• Click-to-Zoom: Click regions to zoom in, click background to zoom out
• Multiple Color Schemes: Support for both linear and categorical color schemes
• Flexible Formatting: Configurable number formatting for metric display
• Comprehensive Coverage: Pre-loaded GeoJSON data for 62+ countries
• Legacy Compatibility: Maintains backward compatibility with existing Superset installations