globe-chart

Lit · globe.gl · country polygons

Country choropleths,
ready for production.

Drop in <globe-chart>, pass ISO + values, and ship a polished 3D map — legend, search, themes, camera, and toast feedback included. MIT for open source; commercial use needs approval.

Install View source

What you get

A small API surface with the pieces you need in a real product.

Choropleth globe

ISO country polygons on globe.gl, flush land caps, readable borders, optional auto-center.

Legend & search

Show/hide, left/right, max height, collapsible toggle (mobile-friendly), paging, local or remote search.

Light & dark

theme="light|dark|auto" plus CSS variables for ocean, scale, legend, and strokes.

Feedback toasts

Skipped rows and init failures surface as in-component toasts and globe-error / globe-warning events.

Configurable

Nested config for colors, camera, labels, globe visuals, and toast placement.

Framework-agnostic

Plain custom element — works with React, Vue, Svelte, or vanilla. One install: npm i globe-chart.

Install

npm install globe-chart

Published on npm. One command, zero configuration: lit, globe.gl, and three install as dependencies, and the country map ships inside the package as a lazily code-split module — no asset copying, no loader plugins, no CDN fetch. Everything stays external to the published bundle so your app does not double-ship WebGL stacks.

Quick start

Framework demos

The same component, integrated idiomatically — each demo is a small open-source app deployed from its own repo.

React

Typed globe-chart/react wrapper with event callbacks. Live demo · Source

Angular

Signals, OnPush, and declarative [prop] bindings. Live demo · Source

Vue

:data.prop bindings and typed @country-select listeners. Live demo · Source

Svelte

Native custom-element property binding, no wrapper at all. Live demo · Source

API overview

Full details live in the README. The essentials:

Properties

Property Attribute Notes
data — Rows with ISO + numeric value
showLegend legend Overlay legend (default off)
theme theme light · dark · auto
config — Legend, colors, camera, toasts…
loading loading Empty rolling globe

Legend height

el.config = {
  legend: {
    title: 'By country',
    maxHeight: '280px', // CSS length
    pageSize: 8,
    search: { enabled: true, mode: 'local' },
  },
};

Collapsible legend

el.config = {
  legend: {
    collapsible: true,
    collapseMode: 'mobile', // 'never' | 'always' | 'mobile'
    collapseOnSelect: 'mobile', // 'never' | 'mobile' | 'always'
    mobileBreakpoint: '(max-width: 768px)',
    toggleLabel: 'Legend',
  },
};

Desktop keeps the panel open after a country click. On mobile, selecting a country collapses back to the button by default. Use collapseOnSelect: 'always' if you want that behavior on every viewport.

Events

Imperative API

el.select('FR');            // highlight + fly to France
el.select(null);            // clear selection
el.flyTo('JP');             // camera only, keeps selection
el.flyTo({ lat: 48.8, lng: 2.3, altitude: 1.5 });
el.selectedIso;             // current selection, or null

Theming

Set theme on the element, or override CSS variables: --globe-chart-ocean-color, --globe-chart-low-color, --globe-chart-high-color, --globe-chart-legend-max-height, and more.

License

Open source (OSI-approved): free under MIT. Proprietary / commercial: written approval required — see COMMERCIAL.md or email benjiar@gmail.com.

Country outlines: Natural Earth 110m admin-0 (public domain).