@ixnode/geo-sphere

@ixnode/geo-sphere is a powerful and flexible Node.js package for rendering interactive maps. It supports various projections (currently only Mercator projection - more are planned), languages, and advanced interactivity, allowing you to display geographical points and create a fully interactive mapping experience.

🚀 Features

• Map Display: Render world maps or other geographical maps in Mercator projection.
• Point Rendering: Display geographical points using latitude and longitude.
• Resizable: Dynamically adjust the map size to fit different screen dimensions.
• Integrated Country Database: Includes all countries with multiple resolution levels by default.
• Interactive Countries: Countries can be clicked, triggering a customizable callback function. Hover and title effects are also supported.
• Multi-language Support: Available in multiple languages: cz|de|en|es|fr|hr|it|pl|sv.
• Mouse and Touch Interaction: The map supports zooming and panning via mouse and touch gestures.
• Lightweight and built with TypeScript
• Build on top with storybook

📦 Installation

npm install @ixnode/geo-sphere

or

yarn add @ixnode/geo-sphere

🔧 Usage

Display example

Example: France is selected, but the mouse is hovering over Berlin, Germany.

Example: The United States are selected. The city Austin was clicked.

Basic Usage

import React from 'react';
import { WorldMap } from '@ixnode/geo-sphere';
import '@ixnode/geo-sphere/dist/styles.css';

const App = () => (
    <WorldMap
        height={500}
        width={1000}
        country="de"
        language="en"
    />
);

export default App;

Usage with country callback function

import React from 'react';
import { WorldMap, CountryData } from '@ixnode/geo-sphere';
import '@ixnode/geo-sphere/dist/styles.css';

const App = () => (
    <WorldMap
        height={500}
        width={1000}
        country="de"
        language="en"
        dataSource="medium"
        onClickCountry={(data: CountryData) => { console.log(data); }}
    />
);

export default App;

The callback function logs something like (according to the clicked country and the given language):

{
    "id": "de",
    "name": "Germany",
    "latitude": 50.304018990688554,
    "longitude": 7.5794992771470975,
    "screenPosition": {
        "x": 401,
        "y": 333
    },
    "svgPosition": {
        "x": 843746,
        "y": 6499094
    }
}

Property	Description
id	The id of clicked element.
name	The translated name of clicked element.
latitude	The latitude value. Clicked on the map.
longitude	The longitude value. Clicked on the map.
screenPosition.x	The x position of the last click. Related to the screen.
screenPosition.y	The y position of the last click. Related to the screen.
svgPosition.x	The x position of the last click. Related to the whole svg map.
svgPosition.y	The x position of the last click. Related to the whole svg map.

Usage with place callback function

import React from 'react';
import { WorldMap, PlaceData } from '@ixnode/geo-sphere';
import '@ixnode/geo-sphere/dist/styles.css';

const App = () => (
    <WorldMap
        height={500}
        width={1000}
        country="de"
        language="en"
        dataSource="medium"
        onClickPlace={(data: PlaceData) => { console.log(data); }}
    />
);

export default App;

The callback function logs something like (according to the clicked place and the given language):

{
    "id": "place-berlin",
    "latitude": 52.5235,
    "longitude": 13.4115,
    "name": "Berlin",
    "population": 3662381, 
    "country": {
        "id": "de",
        "name": "Germany"
    },
    "state": {
        "id": "de-be",
        "name": "Berlin",
        "area": 891.1,
        "population": 3662381
    },
    "screenPosition": {
        "x": 629,
        "y": 295 
    },
    "svgPosition": {
        "x": 1580.7000732421875,
        "y": 6909.73095703125
    }
}

Property	Description
id	The id of clicked element.
name	The translated name of clicked element.
population	The population of clicked element.
latitude	The latitude value. Clicked on the map.
longitude	The longitude value. Clicked on the map.
screenPosition.x	The x position of the last click. Related to the screen.
screenPosition.y	The y position of the last click. Related to the screen.
svgPosition.x	The x position of the last click. Related to the whole svg map.
svgPosition.y	The x position of the last click. Related to the whole svg map.

🔧 Properties

Property	Type	Default	Description
dataSource	'tiny'|'low'|'medium'	'low'	The data source to be used.
country	string|null	null	The country that is marked.
width	number	1000	The width of the map in pixels. Only used for ratio. The svg is always 100% of parent element.
height	number	500	The height of the map in pixels. Only used for ratio. The svg is always 100% of parent element.
language	'cz'|'de'|'en'|'es'|'fr'|'hr'|'it'|'pl'|'sv'	'en'	The language to be used.
onClickCountry	(data: CountryData) => void|null	null	An optional country click handler.
onClickPlace	(data: PlaceData) => void|null	null	An optional place click handler.
onHoverCountry	(data: CountryData) => void|null	null	An optional country hover handler.
onHoverPlace	(data: PlaceData) => void|null	null	An optional place hover handler.
debug	boolean	false	Flag to enable or disable the debug mode.
logo	boolean	true	Flag to enable or disable the logo.

Common countries (country)

Use ISO 3166-1 alpha-2 code to select a country. Examples:

Country	ISO code
United Kingdom of Great Britain and Northern Ireland	gb
United States of America	us
Germany	de
Sweden	se
etc.

See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for more information.

Common languages (language)

Currently supported languages:

Language	Description
cz	Czech
de	German
en	English
es	Spanish
fr	French
hr	Croatian
it	Italian
pl	Polish
sv	Swedish

🛠 Development

Building the Project

To build the project locally:

npm run build

Running Storybook

View and develop components in isolation:

npm run storybook

Open: http://localhost:6006/

Example: The country Portugal and language spanisch is selected, but the mouse is hovering over Madrid, Spain.

📦 Publishing to npm

Check TypeScript Code

• Runs the TypeScript compiler to detect errors without generating any JavaScript output
• Should not throw an error

npx tsc --noEmit

Build the project

• Runs the build process to produce production-ready artifacts
• Test build for a future release process to npmjs.org
• Should not throw an error

npm run build

Verify the build

• Checks that the compiled code runs as expected
• Should not throw an error

ES Modules build

node dist/index.js

or to ignore possible warnings:

node --no-warnings dist/index.js

CommonJS build

node dist/index.cjs

Bump the version

Update the version in the package.json, e.g., from 1.0.0 to 1.0.1, to create a new release:

npm version patch

Alternatively:

• Use npm version minor for new features.
• Use npm version major for breaking changes.

Publish the package

npm publish --access public

Verify the publication

Check the package on npm: https://www.npmjs.com/package/@ixnode/geo-sphere.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Authors

• Björn Hempel [email protected] - Initial work - https://github.com/bjoern-hempel

🌟 Contributing

Contributions are welcome! Feel free to submit issues or pull requests to improve this project.

🤝 Acknowledgments

Special thanks to the open-source community for providing amazing tools like React, TypeScript, and Storybook.