@omnedia/ngx-map

ngx-map

This library is part of the NGXUI ecosystem.
View all available components at https://ngxui.com

@omnedia/ngx-map is an Angular library for creating customizable, animated world maps with dotted grid layouts and path animations. Perfect for visualizing geographic connections, this component offers smooth animations and flexible configurations for diverse use cases.

Features

• Dotted map generation with customizable shapes, colors, and grid styles.
• Path animations between points with configurable delays and durations.
• Responsive design with support for dark and light themes.
• Built-in sanitization for safe SVG rendering.
• Precomputed map support for instant rendering and smaller bundles.
• Web Worker offloading for smooth UI performance.

Installation

Install the library using npm:

npm install @omnedia/ngx-map dotted-map

Usage

Import the NgxMapComponent in your Angular module or component:

import {NgxMapComponent} from '@omnedia/ngx-map';

@Component({
  ...
    imports:
[NgxMapComponent],
...
})

Use the component in your template:

<om-map
  [dots]="[
    { start: { lat: 64.2008, lng: -149.4937 }, end: { lat: 34.0522, lng: -118.2437 } },
    { start: { lat: 34.0522, lng: -118.2437 }, end: { lat: -1.2921, lng: 36.8219 } }
  ]"
  [lineColor]="'#0ea5e9'"
  [animated]="true"
  [mapColor]="'rgba(0, 0, 0, 0.4)'"
  [mapDotsShape]="'circle'"
  [mapDotsRadius]="0.22"
></om-map>

How It Works

• Customizable Dotted Map: Generate maps with dots, specifying their shape, color, and radius.
• Path Animations: Define animated paths between points with adjustable timing.
• Dynamic Theming: The component adapts to dark or light themes via input properties.

API

<om-map
  [dots]="dots"
  [lineColor]="lineColor"
  [backgroundColor]="backgroundColor"
  [mapColor]="mapColor"
  [mapDotsShape]="mapDotsShape"
  [mapDotsRadius]="mapDotsRadius"
  [animated]="animated"
  [styleClass]="styleClass"
  [style]="style"
  [precomputedMap]="precomputedMap"
></om-map>

Inputs:

• dots (required): Array of connection objects, each with start and end properties. Example:

  [
    { start: { lat: 64.2008, lng: -149.4937 }, end: { lat: 34.0522, lng: -118.2437 } }
  ]
  

• lineColor (optional): Color of the animated lines. Defaults to '#0ea5e9'.
• backgroundColor (optional): Background color of the map. Defaults to undefined.
• mapColor (optional): Color of the dots on the map. Defaults to 'rgba(0,0,0,0.40)'.
• mapDotsShape (optional): Shape of the dots ('circle' or 'hexagon'). Defaults to 'circle'.
• mapDotsRadius (optional): Radius of the dots. Defaults to 0.22.
• animated (optional): Whether to animate the paths. Defaults to false.
• styleClass (optional): Custom CSS class for additional styling.
• precomputedMap (optional): Precomputed map JSON (object or string).

🚀 Performance Options

@omnedia/ngx-map now supports two ways to generate maps for maximum performance:

1. Default – Worker-based generation (automatic)

The library automatically uses a Web Worker to offload the heavy dotted-map computation to a background thread. No extra setup required.

2. Precomputed Map (fastest)

If you always use the same map grid, you can precompute it once and ship it as JSON. This completely removes runtime map generation and makes initial render instantaneous.

How to create a precomputed map

Run once in Node:

npm install dotted-map

// scripts/precompute-map.js
const {getMapJSON} = require('dotted-map');
const fs = require('fs');
const path = require('path');

const outputFile = path.resolve('./src/precomputed-map.json');
fs.writeFileSync(outputFile, getMapJSON({height: 100, grid: 'diagonal'}));
console.log('✅ Precomputed map saved:', outputFile);

Run it:

node scripts/precompute-map.js

Using the precomputed map

import precomputedMap from './precomputed-map.json';

@Component({
  standalone: true,
  imports: [NgxMapComponent],
  template: `
    <om-map
      [dots]="dots"
      [precomputedMap]="map"
      [animated]="true"
      [mapColor]="'rgba(0,0,0,0.4)'"
      [backgroundColor]="'#020300'"
    ></om-map>
  `,
})
export class DemoComponent {
  map = precomputedMap;
  dots = [
    {start: {lat: 40.7, lng: -73.9}, end: {lat: 48.8, lng: 2.3}},
  ];
}

Example

<om-map
  [dots]="[
    { start: { lat: 51.5074, lng: -0.1278 }, end: { lat: 40.7128, lng: -74.006 } },
    { start: { lat: 40.7128, lng: -74.006 }, end: { lat: 35.6895, lng: 139.6917 } }
  ]"
  [lineColor]="'#ff5733'"
  [animated]="true"
  [mapColor]="'rgba(255, 87, 51, 0.4)'"
  [mapDotsShape]="'circle'"
  [mapDotsRadius]="0.3"
  styleClass="custom-map"
></om-map>

Styling

.om-map

The .om-map container allows you to apply global or custom styles using the styleClass input. While the component handles dot placement and animations, you can extend styling for the map container or SVG elements.

Example of Global and Custom Styling

<om-map styleClass="custom-map">
</om-map>

.custom-map {
  background-color: #1e1e1e;
  padding: 2rem;
  border-radius: 12px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

Contributing

Contributions are welcome! Please submit a pull request or open an issue to discuss new features or bug fixes.

License

This project is licensed under the MIT License.