Geomap

Creates a geographical map with zooming, panning, image tiles, and the ability to layer choropleth paths and coordinate points.

Choropleth map

Joins data to the topojson shapes via groupBy and fills each region by its colorScale value; colorScaleConfig’s tickFormat renders the legend ticks as percentages.

projection

The map projection for the topojson and coordinate points: a projection function, or the name of one of the d3-geo projections or of geoAlbersUsaTerritories, geoMiller, geoRobinson and geoWinkel3 (e.g. "geoAlbersUsa"). Map tiles only line up with Mercator (the default), so any other projection turns tiles off.

Coordinate point map

Rather than shading regions, this drops a marker per datum: point returns each row’s [longitude, latitude], and pointSize scales the radius between pointSizeMin and pointSizeMax by dma_code.

pointSize

Accessor (or constant) for the value that sizes each coordinate point, scaled by pointSizeScale onto [pointSizeMin, pointSizeMax] pixels.

ƒ (function)

pointSizeMin

The smallest coordinate point radius, in pixels.

pointSizeMax

The largest coordinate point radius, in pixels.

Changing projection

Any d3-geo projection name can be passed to projection; "geoMercator" gives the familiar cylindrical world view, while topojsonFilter drops Antarctica (id !== "010").

projection

Only areas with data

An array of ids passed to topojsonFilter keeps only those features, so the map draws just the areas with data and zooms to fit them. For data that changes, pass a function over the features instead: const ids = new Set(data.map(d => d.id)), then topojsonFilter: f => ids.has(f.id).

const config = {
  data: [
    {id: "840", country: "United States", value: 10},
    {id: "124", country: "Canada", value: 4},
    {id: "484", country: "Mexico", value: 7},
    {id: "076", country: "Brazil", value: 9},
    {id: "032", country: "Argentina", value: 3},
  ],
  colorScale: "value",
  groupBy: "id",
  label: d => d.country,
  topojson: "/data/countries-110m.json",
  topojsonFilter: ["840", "124", "484", "076", "032"],
};

Changing the tileset

Point tileUrl at any XYZ tile server to swap the background imagery. noKeyTilesets lists every server that needs no account or API key: change the name in the code to try another. Esri’s Canvas layers are the default, Light Gray on a light page and Dark Gray on a dark one. The credit in the corner updates to match, and any other {z}/{x}/{y} template works too (Esri’s services order it {z}/{y}/{x}).

const esri = name =>
  `https://server.arcgisonline.com/ArcGIS/rest/services/${name}/MapServer/tile/{z}/{y}/{x}`;

const noKeyTilesets = [
  {
    name: "Esri Light Gray (default)",
    url: esri("Canvas/World_Light_Gray_Base"),
  },
  {
    name: "Esri Dark Gray (dark default)",
    url: esri("Canvas/World_Dark_Gray_Base"),
  },
  {name: "Esri Terrain", url: esri("World_Terrain_Base")},
  {name: "Esri Street Map", url: esri("World_Street_Map")},
  {name: "Esri Imagery", url: esri("World_Imagery")},
  {name: "Esri National Geographic", url: esri("NatGeo_World_Map")},
  {name: "OSM Standard", url: "https://tile.openstreetmap.org/{z}/{x}/{y}.png"},
  {
    name: "OSM Humanitarian",
    url: "https://{s}.tile.openstreetmap.fr/hot/{z}/{x}/{y}.png",
  },
  {name: "OpenTopoMap", url: "https://tile.opentopomap.org/{z}/{x}/{y}.png"},
];

const config = {
  projection: "geoMercator",
  tileUrl: noKeyTilesets.find(t => t.name === "Esri Terrain").url,
};

Light and dark tiles

tileUrl and ocean also accept a {light, dark} pair, and the defaults are one: Esri Light Gray Canvas on a light backdrop and Dark Gray Canvas on a dark one, with a matching ocean and no-data fill. Geomap reads the backdrop from the page (the nearest background color, or a dark color-scheme on a dark system) and redraws when it changes: switch this site between light and dark to see it.

const esri = name =>
  `https://server.arcgisonline.com/ArcGIS/rest/services/${name}/MapServer/tile/{z}/{y}/{x}`;

const noKeyTilesets = [
  {
    name: "Esri Light Gray (default)",
    url: esri("Canvas/World_Light_Gray_Base"),
  },
  {
    name: "Esri Dark Gray (dark default)",
    url: esri("Canvas/World_Dark_Gray_Base"),
  },
  {name: "Esri Terrain", url: esri("World_Terrain_Base")},
  {name: "Esri Street Map", url: esri("World_Street_Map")},
  {name: "Esri Imagery", url: esri("World_Imagery")},
  {name: "Esri National Geographic", url: esri("NatGeo_World_Map")},
  {name: "OSM Standard", url: "https://tile.openstreetmap.org/{z}/{x}/{y}.png"},
  {
    name: "OSM Humanitarian",
    url: "https://{s}.tile.openstreetmap.fr/hot/{z}/{x}/{y}.png",
  },
  {name: "OpenTopoMap", url: "https://tile.opentopomap.org/{z}/{x}/{y}.png"},
];

const config = {
  projection: "geoMercator",
  // The default, spelled out: any two tile servers can be paired this way.
  tileUrl: {
    light: noKeyTilesets[0].url,
    dark: noKeyTilesets[1].url,
  },
  ocean: {light: "#d0cfd4", dark: "#222327"},
};

Changing no data color

topojsonFill sets the color for shapes with no matching data (here light pink), so empty regions read differently from those on the colorScale.

topojsonFill

The fill for topojson shapes that have no data (or no colorScale value): a CSS color or a function of the feature. Defaults to the theme's colorScale.missing when it sets one, else a quiet light gray, or its dark counterpart over a dark basemap.

Custom colors

Override the default color interpolation by passing an explicit ramp to colorScaleConfig’s color array — here red → orange → yellow → green → blue across the range.

const config = {
  data: "https://api.datausa.io/tesseract/data.jsonrecords?cube=county_health_ranking&drilldowns=State&measures=Diabetes%20Prevalence&Year=2025",
  groupBy: "State ID",
  colorScale: "Diabetes Prevalence",
  colorScaleConfig: {
    color: ["red", "orange", "yellow", "green", "blue"],
  },
  projection: "geoAlbersUsa",
  topojson: "https://datausa.io/topojson/State.json",
};

Custom zoom

fitObject frames the initial view to a custom TopoJSON object; the two MultiPoint corners here define the bounding box the map zooms to fit.

const config = {
  fitObject: {
    type: "Topology",
    objects: {
      "custom-bounds": {
        type: "GeometryCollection",
        geometries: [
          {
            type: "MultiPoint",
            coordinates: [
              [-160, 70],
              [170, -55],
            ],
          },
        ],
      },
    },
  },
};

Disable zooming

zoom: false turns off panning and scroll-to-zoom, locking the map at its initial extent.

const config = {
  data: "https://api.datausa.io/tesseract/data.jsonrecords?cube=county_health_ranking&drilldowns=State&measures=Diabetes%20Prevalence&Year=2025",
  groupBy: "State ID",
  colorScale: "Diabetes Prevalence",
  projection: "geoAlbersUsa",
  topojson: "https://datausa.io/topojson/State.json",
  zoom: false,
};

Hiding the color scale

colorScalePosition: false hides the legend while regions stay shaded by colorScale — useful when the scale is documented elsewhere.

const config = {
  data: "https://api.datausa.io/tesseract/data.jsonrecords?cube=county_health_ranking&drilldowns=State&measures=Diabetes%20Prevalence&Year=2025",
  groupBy: "State ID",
  colorScale: "Diabetes Prevalence",
  colorScalePosition: false,
  projection: "geoAlbersUsa",
  topojson: "https://datausa.io/topojson/State.json",
};

Overriding colorscale behavior

The color scale normally auto-detects its type from the data; setting colorScaleConfig’s scale: "linear" forces a plain linear ramp instead of the automatic choice.

const config = {
  // Illustrative year-over-year growth in one country's exports to each
  // trading partner, keyed by the ISO 3166 numeric code the map's features use.
  data: [
    {id: "840", name: "United States", "Export Growth": 0.047},
    {id: "250", name: "France", "Export Growth": -0.013},
    {id: "156", name: "China", "Export Growth": 0.028},
    {id: "528", name: "Netherlands", "Export Growth": -0.021},
    {id: "826", name: "United Kingdom", "Export Growth": -0.043},
    {id: "380", name: "Italy", "Export Growth": -0.031},
    {id: "040", name: "Austria", "Export Growth": -0.009},
    {id: "616", name: "Poland", "Export Growth": 0.032},
    {id: "756", name: "Switzerland", "Export Growth": 0.054},
    {id: "056", name: "Belgium", "Export Growth": -0.028},
    {id: "724", name: "Spain", "Export Growth": -0.017},
    {id: "203", name: "Czechia", "Export Growth": -0.006},
    {id: "752", name: "Sweden", "Export Growth": -0.052},
    {id: "348", name: "Hungary", "Export Growth": 0.018},
    {id: "643", name: "Russia", "Export Growth": 0.011},
    {id: "392", name: "Japan", "Export Growth": 0.035},
    {id: "792", name: "Turkey", "Export Growth": -0.087},
    {id: "208", name: "Denmark", "Export Growth": 0.004},
    {id: "642", name: "Romania", "Export Growth": 0.029},
    {id: "703", name: "Slovakia", "Export Growth": 0.021},
    {id: "484", name: "Mexico", "Export Growth": 0.066},
    {id: "124", name: "Canada", "Export Growth": 0.038},
    {id: "076", name: "Brazil", "Export Growth": -0.048},
    {id: "356", name: "India", "Export Growth": -0.035},
    {id: "410", name: "South Korea", "Export Growth": -0.072},
    {id: "036", name: "Australia", "Export Growth": -0.059},
    {id: "578", name: "Norway", "Export Growth": -0.024},
    {id: "246", name: "Finland", "Export Growth": -0.033},
    {id: "620", name: "Portugal", "Export Growth": 0.015},
    {id: "710", name: "South Africa", "Export Growth": -0.091},
  ],
  groupBy: "id",
  label: d => d.name,
  colorScale: "Export Growth",
  colorScaleConfig: {
    scale: "linear",
  },
  projection: "geoMiller",
  topojson: "/data/countries-110m.json",
  topojsonFilter: d => d.id !== "010",
};

Removing ocean and tiles

Set ocean: "transparent" and tiles: false to strip the water fill and background map tiles, leaving just the choropleth shapes.

const config = {
  data: "https://api.datausa.io/tesseract/data.jsonrecords?cube=county_health_ranking&drilldowns=State&measures=Diabetes%20Prevalence&Year=2025",
  groupBy: "State ID",
  colorScale: "Diabetes Prevalence",
  colorScaleConfig: {
    axisConfig: {
      tickFormat: d => `${(d * 100).toFixed(1)}%`,
    },
  },
  ocean: "transparent",
  projection: "geoAlbersUsa",
  tiles: false,
  topojson: "https://datausa.io/topojson/State.json",
};

Rendering to canvas

The same choropleth painted with the Canvas backend (renderer: "canvas"). Geography, color scale, tooltips, and zoom all work; SVG remains the default.

renderer

Selects which @d3plus/render backend paints the visible output. "svg" = SvgRenderer (default), "canvas" = CanvasRenderer. Boolean arguments both normalize to "svg".

falsetruesvgcanvas

Point motion trails

Motion trails aren’t just for scatter plots — Geomap coordinate points trail too, and are on by default. Press play: each storm track sweeps a tapering cone from its previous position to the next as the timeline advances, tracing its path across the map. Toggle renderer to compare the SVG and Canvas backends.

renderer

Selects which @d3plus/render backend paints the visible output. "svg" = SvgRenderer (default), "canvas" = CanvasRenderer. Boolean arguments both normalize to "svg".

falsetruesvgcanvas

time

Accessor function or string key for the time dimension of each data point.

Point size legend

Coordinate points sized by pointSize get a size legend in the corner, drawn with the same pointSizeScale as the points. The points scale with the map as you zoom in, so the legend keeps its circles the same size and relabels them: at 4× zoom, the largest circle represents a much smaller population than it does unzoomed.

pointSize

Accessor (or constant) for the value that sizes each coordinate point, scaled by pointSizeScale onto [pointSizeMin, pointSizeMax] pixels.

ƒ (function)

pointSizeMin

The smallest coordinate point radius, in pixels.

pointSizeMax

The largest coordinate point radius, in pixels.

Side color scale

A left or right colorScalePosition fits the scale between everything above and below the map (a title, a top legend, a timeline), and starts it below the control buttons in the corner on its side, so the buttons never cover the scale’s top label.

const config = {
  data: "https://api.datausa.io/tesseract/data.jsonrecords?cube=county_health_ranking&drilldowns=State&measures=Diabetes%20Prevalence&Year=2025",
  groupBy: "State ID",
  colorScale: "Diabetes Prevalence",
  colorScaleConfig: {scale: "linear"},
  colorScalePosition: "left",
  projection: "geoAlbersUsa",
  tableView: true,
  topojson: "https://datausa.io/topojson/State.json",
};

Configuration

import {Geomap} from "@d3plus/core";

Extends Viz.

Filter 39 config keys

activefalse | function

The active callback function for highlighting shapes.

classNamestring | array.<string> | undefined

CSS classes added to the outermost element this chart or component draws into, next to its fixed d3plus classes, so page CSS can target it: a chart's root <svg class="d3plus-viz"> (its <canvas> with the Canvas renderer) and a standalone component's <svg>. Takes a space-separated string or an array. A new value replaces the classes the previous one added; unset adds none. Tooltips take their own tooltipConfig.className.

colorDefaultscolordefaultsconfig

Overrides the default colors used when assigning fills from data and choosing legible text colors: dark and light (the text colors picked for contrast against a background), missing (null/undefined values), on/off (true/false values), sequential (the anchor hue for magnitude ramps), and scale (the categorical palette, given as a d3 ordinal scale or an array of colors). Keys are merged into the current defaults, and a Viz passes its overrides down to the shapes and components it draws.

configd3plusconfig

Methods that correspond to the key/value pairs and returns this class.

datastring | array.<datapoint> | object

The primary data array used to draw the visualization. The value passed should be an Array of objects or a String representing a filepath or URL to be loaded. The following filetypes are supported: csv, tsv, txt, and json.

If your data URL needs specific headers to be set, an Object with a "url" and "headers" (or any other fetch request option) may also be passed. An Object with any other key is a data row, not a request.

Additionally, a custom formatting function can be passed as a second argument to this method. This custom function will be passed the data that has been loaded, as long as there are no errors. This function should return the final array of obejcts to be used as the primary data array. For example, some JSON APIs return the headers split from the data values to save bandwidth. These would need be joined using a custom formatter.

If you would like to specify certain configuration options based on the yet-to-be-loaded data, you can also return a full config object from the data formatter (including the new data array as a key in the object).

To re-fetch a URL on an interval and redraw when its data changes, set dataPollingInterval; each poll runs the same formatter.

Defaults to an empty array ([]).

Splits the chart into small multiples: a grid of equally sized panels, one per distinct value of this data key or accessor, each drawing the chart for that value's rows. The panels share one legend, color scale, title, and timeline, color each series the same way, and hover, tooltips, and legend clicks apply across all of them. Pass false to draw a single chart. See facetConfig for the grid's layout and shared scales.

facetConfigfacetconfig

Configuration for small multiples (see facet), merged into the current config: - columns / rows: the grid's shape. Chosen by default to make the panels as large as the chart's shape allows. - padding: the space between panels, in pixels (default 20). - sort: panel order — "ascending" (default), "descending", "data" (first appearance), a comparator over facet values, or an Array of values. - scales: "shared" (default) gives every panel of a chart with axes the same x/y domains; "independent" fits each panel to its own rows. Funnel defaults to "independent" (each panel sized to its own widest stage); "shared" sizes every panel against the widest stage across all panels. PolarArea and RadialBar default to "independent" (each panel's rings and ticks fit its own values); "shared" gives every panel the same value domain. - axes: with shared scales, "outer" (default) labels the axes only along the grid's left and bottom edges; "all" labels every panel. An object sets each axis on its own, as in {x: "all", y: "outer"}: every panel labels its x axis, only the left column labels its y axis, and the panels' plot areas line up. BumpChart defaults to "all", and Marimekko labels its categories on every panel and its 0–100% share axis only along the outer edge, even with independent scales. - title: a (value, data) => string function for each panel's title, or false to hide panel titles. - titleConfig: TextBox config for the panel titles (fontSize, fontWeight, fontColor, textAnchor, padding, …).

fitObjectstring | object | falseDefault false

The topojson the initial projection fits its extent to (fitExtent): a topojson object, or a filepath or URL to load. An optional formatting function, passed as a second argument, receives the loaded data and returns the final topojson object. Defaults to topojson, or to the coordinate points when there is none.

fontFamilystring | array.<string>

The font family used throughout the visualization.

groupBystring | function | array.<string | function>

Defines the mapping between data and shape. The value can be a String matching a key in each data point (default is "id"), or an accessor Function that returns a unique value for each data point. Additionally, an Array of these values may be provided if the visualization supports nested hierarchies.

highlightfalse | function

Persistently emphasizes the data points matching the given predicate: the matching marks keep their color while every other mark is de-emphasized to a neutral gray (the "emphasis" form — highlight one series, gray the rest). Unlike hover/active (transient, opacity-based), highlight is a standing state that survives pointer movement. Pass false to clear it.

hoverfalse | function

The hover callback function for highlighting shapes on mouseover.

localestring | object

The locale used for all text and number formatting. Supports the locales defined in d3plus-format. The locale can be a complex Object, a locale code (like "en-US"), or a 2-digit language code (like "en"). If a 2-digit code is provided, the "findLocale" function is used to identify the most approximate locale.

noDataMessagebooleanDefault false

Toggles the visibility of the status message that is displayed when no data is supplied to the visualization.

oceanstring | {light: string, dark: string}Default DEFAULT_OCEAN

The color behind the map's shapes and tiles: any CSS color (including "transparent"), or a {light, dark} pair chosen by the chart's backdrop. Defaults to the default basemap's own water colors, which mask the tiles while they load.

onstring

Event listener for the specified event typenames. Mirrors the core d3-selection behavior.

parentunknown

Parent config used by the wrapper.

pointnumber[] | functionDefault "point"

Accessor function for each data point's coordinates, as [longitude, latitude] (d3's coordinate order), or one coordinate for every point. Defaults to each row's point key. Rows with a coordinate are drawn as points; the rest are matched to topojson shapes.

pointSizenumber | functionDefault 1

Accessor (or constant) for the value that sizes each coordinate point, scaled by pointSizeScale onto [pointSizeMin, pointSizeMax] pixels.

pointSizeMaxnumberDefault 10

The largest coordinate point radius, in pixels.

pointSizeMinnumberDefault 5

The smallest coordinate point radius, in pixels.

pointSizeScaleunknownDefault "linear"

The continuous d3-scale that sizes coordinate points from pointSize, by name (e.g. "sqrt").

projectionstring | functionDefault geoMercator()

projectionPaddingnumber | stringDefault parseSides(20)

The outer padding between the edge of the visualization and the map's shapes: one number for every side, or a CSS-style string (e.g. "20px 0 10px").

renderfunction

Draws the visualization given the specified configuration.

rendererboolean | "svg" | "canvas"

Selects which @d3plus/render backend paints the visible output. "svg" = SvgRenderer (default), "canvas" = CanvasRenderer. Boolean arguments both normalize to "svg".

selectstring | htmlelement

The SVG container element as a d3 selector or DOM element. Defaults to undefined.

shapestring | functionDefault "Circle"

Changes the primary shape used to represent each data point in a visualization. Not all visualizations support changing shapes, this method can be provided the String name of a D3plus shape class (for example, "Rect" or "Circle"), or an accessor Function that returns the String class name to be used for each individual data point.

shapeConfigd3plusconfig

Configuration object with key/value pairs applied as method calls on each shape.

thresholdnumber | function

The threshold value for bucketing small data points together, as a share of the total. On a stacked Plot, the series whose summed value across every position is under that share of the whole chart's total merge into one series, stacked on top. A bucket needs at least two items, and its tooltips list them. Off (0) by default on Plot charts.

thresholdKeystring | function

Accessor for the value used in the threshold algorithm. A stacked Plot defaults to its stacked value.

timestring | false | function

Accessor function or string key for the time dimension of each data point.

timelineDefaultstring | date | array.<string | date>

The starting time or range for the timeline. Can be a single Date/String, or an Array of 2 values representing the min and max.

topojsonstring | object | falseDefault false

The topojson to draw as geographic paths: a topojson object, or a filepath or URL to load. An optional formatting function, passed as a second argument, receives the loaded data and returns the final topojson object.

topojsonFillCssColor | functionDefault "#f5f5f3"

topojsonFilterstring | string[] | ((feature: object) => boolean)Default !["010"].includes(d.id as string)

Limits which topojson features are drawn: a single feature id or an array of ids keeps only those features, and a filter function keeps the features it returns true for. To draw only the areas that have data, filter on the ids in your data (e.g. const ids = new Set(data.map(d => d.id)); then f => ids.has(f.id)). Defaults to a filter that hides Antarctica (id "010").

topojsonIdstring | functionDefault "id"

The accessor, or key, that reads each topojson feature's id, which is matched against each data point's id (its groupBy value) to join the data to the map.

totalstring | boolean | function

Accessor function or string key for the total value displayed in the visualization.

translatefunction

Defines how informational text strings should be displayed. By default, this function will try to find the string in question (which is the first argument provided to this function) inside of an internally managed translation Object. If you'd like to override to use custom text, simply pass this method your own custom formatting function.