@ixnode/geo-sphere NPM

@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

yarn add @ixnode/geo-sphere

🔧 Usage

Display example

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

Basic world.

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

Basic world.

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.