Skip to content

OrigamChartMap ​

World map chart family. Two rendering modes selectable via the mode prop:

  • mode='choropleth' — country shapes filled with an interpolated colour from colorRange, proportional to each country's value. Countries absent from the dataset receive defaultCountryFill.
  • mode='flight-routes' — quadratic Bezier arcs drawn between country-centroid pairs over a neutral map backdrop. Stroke width scales logarithmically with the optional value on each route.

Map coverage: 35 countries on a simplified 1000 × 500 Mercator canvas. See "Coverage" below for the full list and omitted countries.

Import ​

ts
import { OrigamChartMap } from '@origam/ds'

Quick start — Choropleth ​

vue
<template>
  <origam-chart-map
    mode="choropleth"
    :series="[{
      name: 'GDP (T USD)',
      data: [
        { code: 'US', value: 27.4, name: 'United States' },
        { code: 'CN', value: 17.7, name: 'China' },
        { code: 'DE', value: 4.4,  name: 'Germany' }
      ]
    }]"
    :height="400"
    title="GDP by Country"
  />
</template>

<script setup lang="ts">
import { OrigamChartMap } from '@origam/ds'
</script>

Quick start — Flight routes ​

vue
<template>
  <origam-chart-map
    mode="flight-routes"
    :series="[{
      name: 'Routes from London',
      data: [
        { from: 'GB', to: 'US', value: 850 },
        { from: 'GB', to: 'JP', value: 280 },
        { from: 'GB', to: 'AU', value: 220 }
      ]
    }]"
    :height="400"
    :route-curvature="0.3"
    :show-legend="false"
    title="Routes from GB"
  />
</template>

<script setup lang="ts">
import { OrigamChartMap } from '@origam/ds'
</script>

Data shapes ​

Choropleth datum (IChartMapChoroplethDatum) ​

FieldTypeRequiredDescription
codestringYesISO-3166-1 alpha-2 country code (e.g. 'FR', 'US').
valuenumberYesNumeric value for colour interpolation.
namestringNoHuman-readable label. Falls back to code.

Route datum (IChartMapRouteDatum) ​

FieldTypeRequiredDescription
fromstringYesISO-3166-1 alpha-2 code for the origin country.
tostringYesISO-3166-1 alpha-2 code for the destination country.
valuenumberNoFlow weight — drives stroke width via Math.log(value + 1) * 1.5. Constant 2 when absent.
colorTIntent | stringNoPer-route stroke colour override. Falls back to lineColor prop.

Props ​

Data ​

NameTypeDefaultDescription
seriesArray<IChartSeries>requiredSingle series. Data shape depends on mode: IChartMapChoroplethDatum[] for choropleth, IChartMapRouteDatum[] for flight-routes.

Visual ​

NameTypeDefaultDescription
modeTChartMapMode'choropleth'Rendering mode. 'choropleth' or 'flight-routes'.
heightnumber | string—Optional cap on the chart height in px (the map is 2:1). Ignored when aspectRatio is set.
aspectRatiostringundefinedCSS aspect-ratio shorthand — overrides height.
titlestringundefinedOptional title above the chart. Replaceable via #title slot.
subtitlestringundefinedOptional subtitle below the title.
colorRange[TIntent | string, TIntent | string]['info', 'danger']Choropleth gradient endpoints. First = min value, second = max value.
defaultCountryFillTIntent | string'rgba(0,0,0,0.08)'Fill for countries absent from the dataset (both modes). Supports intent names and raw CSS strings, resolved the same way as borderColor / lineColor. Default stays the literal — it is a semi-transparent scrim composited over the chart's own bgColor, which no fixed intent token reproduces.
borderColorTIntent | string'neutral'Stroke applied to all country paths. Supports intent names and raw CSS strings, resolved the same way as lineColor.
lineColorTIntent | string'primary'Default stroke colour for flight-route arcs. Overridden per route.
nodeRadiusnumber4Radius of the endpoint circles in flight-routes mode.
routeCurvaturenumber0.3Bezier offset as a fraction of chord length [0..1]. 0 = straight.
colorSchemeArray<TIntent | string>[]⛔ Sans effet sur ce composant — colour is a continuous gradient (colorRange, choropleth mode) or a single lineColor (flight-routes mode) — a rotating discrete palette does not apply to either. La prop reste declaree (elle est heritee d'IChartBaseProps) et emet un avertissement de developpement si elle est passee. Voir #426.

Legend ​

NameTypeDefaultDescription
showLegendbooleantrueToggle the gradient legend bar (choropleth). Has no visible effect in flight-routes mode (no legend rendered).
legendPositionTChartLegendPosition'bottom'⛔ Sans effet sur ce composant — the legend gradient is placed by the fixed coordinates of gradientRect, which never read the anchor. La prop reste declaree (elle est heritee d'IChartBaseProps) et emet un avertissement de developpement si elle est passee. Voir #426.

Behaviour ​

NameTypeDefaultDescription
showTooltipbooleantrueToggle the hover tooltip.
animatedbooleantrueFade-in animation on mount. Respects prefers-reduced-motion.
animationDurationnumber600Animation duration in ms.
yAxisFormat(value: number) => stringundefinedValue formatter used in tooltips and the gradient legend labels.

Inherited from IChartBaseProps ​

bgColor, elevation, rounded, margin, padding — see base props.

colorScheme is also inherited but has no effect on this component (see Behaviour notes).

Emits ​

EventPayloadDescription
point-click(point: IChartPoint, event: MouseEvent | KeyboardEvent)Fires when a choropleth country with data (or a flight-route arc) is activated by click or Enter/Space.

IChartMapEmits does not include legend-click / series-toggle (#545) — the map's series represent choropleth regions / flight routes, not a discrete toggleable legend list, so there is no legend entry for either event to report.

Slots ​

SlotBindingsDescription
#tooltip{ point, series, category }Replace the default tooltip body.
#title—Replace the title + subtitle block.
#empty—Render when series is empty or has no renderable data.

Coverage ​

Countries included in the simplified map (35 total):

RegionCountries
North AmericaUS, CA, MX
South AmericaBR, AR, CL, PE, CO
EuropeGB, FR, DE, IT, ES, PT, NL, BE, PL, SE, NO, FI, GR, TR
AsiaRU, CN, JP, KR, IN, TH, SG, ID
AfricaZA, EG, NG
OceaniaAU, NZ

Omitted (hard to approximate clearly at 1000×500 scale, or too small):

  • Central African countries, Saharan countries between EG/NG/ZA
  • Small island states beyond SG and NZ
  • Eastern European countries between DE/PL and TR/GR

Behaviour notes ​

Responsive 2:1 drawing surface (#1324). The SVG viewBox follows the measured width of the container (useChartSize, a ResizeObserver) and its height is half that width, so the geography is never distorted. Countries are re-projected to the measured box, and legend text and strokes keep their real pixel size. height is an optional cap: when set, the width is reduced to keep the 2:1 ratio. Until the box is measured (SSR, first paint) the 1000 × 500 fallback is used, so hydration is unchanged.

  • SVG-only — no canvas fallback, no external map library.
  • Projection — simplified Mercator on a fixed 1000×500 coordinate space. Shapes are recognisable approximations, not GIS-accurate.
  • Choropleth colour interpolation — uses color-mix(in srgb, …). Requires a browser with color-mix() support (Baseline 2023). Falls back to the start colour in unsupported environments.
  • Keyboard navigation — choropleth countries with data and route arcs are keyboard-focusable (one roving tab stop, arrows move between them, Enter/Space activate point-click — see the OrigamChart page). Countries without data are not focusable. Arrow keys follow the DOM order: countries with data first (in map order), then the route arcs (in routes order) — not the geographic neighbour.
  • Animation — prefers-reduced-motion: reduce disables all animations automatically.
  • Route curvature edge cases — at routeCurvature=0 the arc degenerates to a straight line. At values above 0.6 the perpendicular offset may push the control point outside the SVG viewport on short inter-country chords; 0.3–0.4 is the recommended range.
  • colorScheme has no effect (#426). It's inherited from IChartBaseProps and stays on the public API for consistency across chart types, but colour is a continuous gradient in choropleth mode (colorRange) or a single lineColor in flight-routes mode — neither has a per-series identity a rotating discrete palette could drive. Passing it logs [origam] <OrigamChartMap> prop "colorScheme" has no effect on this component: … once to the console in dev builds (silent in production). Neither wiring a fake behaviour nor removing the prop was on the table — see the #426 decision.

Composable ​

No dedicated composable — geometry logic lives inside the component as computed properties, following the heatmap/pyramid pattern.