Awesome
d3plus-geomap
A reusable geo map built on D3 and Topojson
Installing
If using npm, npm install d3plus-geomap. Otherwise, you can download the latest release from GitHub or load from a CDN.
import modules from "d3plus-geomap";
d3plus-geomap can be loaded as a standalone library or bundled as part of D3plus. ES modules, AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3plus global is exported:
<script src="https://cdn.jsdelivr.net/npm/d3plus-geomap@1"></script>
<script>
console.log(d3plus);
</script>
Examples
Live examples can be found on d3plus.org, which includes a collection of example visualizations using d3plus-react. These examples are powered by the d3plus-storybook repo, and PRs are always welcome. :beers:
API Reference
<a name="Geomap"></a>
Geomap <>
This is a global class, and extends all of the methods and functionality of <code>Viz</code>.
- Geomap ⇐ <code>Viz</code>
- new Geomap()
- .fitFilter([value]) ↩︎
- .fitKey(value) ↩︎
- .fitObject(data, [formatter]) ↩︎
- .ocean([value]) ↩︎
- .point([value]) ↩︎
- .pointSize([value]) ↩︎
- .pointSizeMax([value]) ↩︎
- .pointSizeMin([value]) ↩︎
- .projection(projection) ↩︎
- .projectionPadding([value]) ↩︎
- .projectionRotate([value]) ↩︎
- .tiles([value]) ↩︎
- .tileUrl([url]) ↩︎
- .topojson(data, [formatter]) ↩︎
- .topojsonFill(value) ↩︎
- .topojsonFilter([value]) ↩︎
- .topojsonKey(value) ↩︎
- .topojsonId(value) ↩︎
<a name="new_Geomap_new" href="#new_Geomap_new">#</a> new Geomap()
Creates a geographical map with zooming, panning, image tiles, and the ability to layer choropleth paths and coordinate points. See this example for help getting started.
<a name="Geomap.fitFilter" href="#Geomap.fitFilter">#</a> Geomap.fitFilter([value]) <>
Topojson files sometimes include small geographies that negatively impact how the library determines the default zoom level (for example, a small island or territory far off the coast that is barely visible to the eye). The fitFilter method can be used to remove specific geographies from the logic used to determine the zooming.
The value passed can be a single id to remove, an array of ids, or a filter function. Take a look at the Choropleth Example to see it in action.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.fitKey" href="#Geomap.fitKey">#</a> Geomap.fitKey(value) <>
If the topojson being used to determine the zoom fit (either the main topojson object or the fitObject) contains multiple geographical sets (for example, a file containing state and county boundaries), use this method to indentify which set to use for the zoom fit.
If not specified, the first key in the Array returned from using Object.keys on the topojson will be used.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.fitObject" href="#Geomap.fitObject">#</a> Geomap.fitObject(data, [formatter]) <>
The topojson to be used for the initial projection fit extent. The value passed should either be a valid Topojson Object or a String representing a filepath or URL to be loaded.
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 needs to return the final Topojson Object.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
| Param | Type | Description |
|---|---|---|
| data | <code>Object</code> | <code>String</code> | = undefined |
| [formatter] | <code>function</code> |
<a name="Geomap.ocean" href="#Geomap.ocean">#</a> Geomap.ocean([value]) <>
The color visible behind any shapes drawn on the map projection. By default, a color value matching the color used in the map tiles is used to help mask the loading time needed to render the tiles. Any value CSS color value may be used, including hexidecimal, rgb, rgba, and color strings like "blue" and "transparent".
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.point" href="#Geomap.point">#</a> Geomap.point([value]) <>
The accessor to be used when detecting coordinate points in the objects passed to the data method. Values are expected to be in the format [longitude, latitude], which is in-line with d3's expected coordinate mapping.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.pointSize" href="#Geomap.pointSize">#</a> Geomap.pointSize([value]) <>
The accessor or static value to be used for sizing coordinate points.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.pointSizeMax" href="#Geomap.pointSizeMax">#</a> Geomap.pointSizeMax([value]) <>
The maximum pixel radius used in the scale for sizing coordinate points.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.pointSizeMin" href="#Geomap.pointSizeMin">#</a> Geomap.pointSizeMin([value]) <>
The minimum pixel radius used in the scale for sizing coordinate points.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.projection" href="#Geomap.projection">#</a> Geomap.projection(projection) <>
Sets the map projection used when displaying topojson and coordinate points. All of the projections exported from d3-geo, d3-geo-projection, and d3-composite-projections are accepted, whether as the string name (ie. "geoMercator") or the generator function itself. Map tiles are only usable when the projection is set to Mercator (which is also the default value).
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.projectionPadding" href="#Geomap.projectionPadding">#</a> Geomap.projectionPadding([value]) <>
The outer padding between the edge of the visualization and the shapes drawn. The value passed can be either a single number to be used on all sides, or a CSS string pattern (ie. "20px 0 10px").
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.projectionRotate" href="#Geomap.projectionRotate">#</a> Geomap.projectionRotate([value]) <>
An array that corresponds to the value passed to the projection's rotate function. Use this method to shift the centerpoint of a map.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.tiles" href="#Geomap.tiles">#</a> Geomap.tiles([value]) <>
Toggles the visibility of the map tiles.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.tileUrl" href="#Geomap.tileUrl">#</a> Geomap.tileUrl([url]) <>
By default, d3plus uses the light_all style provided by CARTO for it's map tiles. The tileUrl method changes the base URL used for fetching the tiles, as long as the string passed contains {x}, {y}, and {z} variables enclosed in curly brackets for the zoom logic to load the correct tiles.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.topojson" href="#Geomap.topojson">#</a> Geomap.topojson(data, [formatter]) <>
The topojson to be used for drawing geographical paths. The value passed should either be a valid Topojson Object or a String representing a filepath or URL to be loaded.
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 Topojson Obejct.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
| Param | Type | Description |
|---|---|---|
| data | <code>Object</code> | <code>String</code> | = [] |
| [formatter] | <code>function</code> |
<a name="Geomap.topojsonFill" href="#Geomap.topojsonFill">#</a> Geomap.topojsonFill(value) <>
The function is used to set default color of the map.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.topojsonFilter" href="#Geomap.topojsonFilter">#</a> Geomap.topojsonFilter([value]) <>
If the topojson being used contains boundaries that should not be shown, this method can be used to filter them out of the final output. The value passed can be a single id to remove, an array of ids, or a filter function.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.topojsonKey" href="#Geomap.topojsonKey">#</a> Geomap.topojsonKey(value) <>
If the topojson contains multiple geographical sets (for example, a file containing state and county boundaries), use this method to indentify which set to use.
If not specified, the first key in the Array returned from using Object.keys on the topojson will be used.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.
<a name="Geomap.topojsonId" href="#Geomap.topojsonId">#</a> Geomap.topojsonId(value) <>
The accessor used to map each topojson geometry to it's corresponding data point.
This is a static method of <code>Geomap</code>, and is chainable with other methods of this Class.