@bluehalo/ngx-leaflet

v21.2.1

Published

5 days ago

Angular.io components for Leaflet

0High
0Medium
0Low

@bluehalo/ngx-leaflet

Leaflet packages for Angular.io. Provides flexible and extensible components for integrating Leaflet v0.7.x and v1.x into Angular.io projects.

Install

Install the package and its peer dependencies via npm (or yarn):

npm install leaflet
npm install @bluehalo/ngx-leaflet

If you intend to use this library in a typescript project (utilizing the typings), you'll need to install the leaflet typings:

npm install --save-dev @types/leaflet

If you want to run the demo, clone the repository, perform an npm install, npm run demo and then go to http://localhost:4200

Not using the latest version of Angular.io? Have a look in CHANGES.md to find the right version for your project.

Usage

NOTE: We've simplified the getting started instructions to be more targeted at the most recent versions of Angular.io and the use of Angular CLI.

Generally, the steps are:

Install Leaflet, this library, and potentially the Leaflet typings (see above).
Import the Leaflet stylesheet
Import the LeafletDirective etc. into your Module or standalone Component
Create and configure a map (see docs below and/or demo)

Alternatively, you can use the LeafletModule to import the module into your application.

Import the Leaflet Stylesheet

For leaflet to work, you need to have the leaflet stylesheets loaded into your application. If you've installed via npm, you will need to load ./node_modules/leaflet/dist/leaflet.css. How you include the stylesheet will depend on your specific setup. Here are a few examples:

Direct Import from HTML

If you are just building a webpage and not using a bundler for your css, you'll want to directly import the css file in your HTML page.

<head>
	...
	<link rel="stylesheet" type="text/css" href="./node_modules/leaflet/dist/leaflet.css">
	...
</head>

Adding Styles in Angular CLI

If you are using Angular CLI, you will need to add the Leaflet CSS file to the styles array contained in angular.json

{
	...
	"styles": [
		"styles.css",
		"./node_modules/leaflet/dist/leaflet.css"
	],
	...
}

A Note About Markers

Leaflet marker URLs don't play well with the Angular CLI build pipeline without some special handling. See Marker Setup in the cookbook for the full configuration steps.

Import LeafletDirective

Before you can use the Leaflet components in your Angular.io app, you'll need to import it in your application. Depending on if you're using standalone mode or not, you will import it into your modules and/or components.

import { LeafletDirective } from '@bluehalo/ngx-leaflet';

@Component({
    imports: [
        LeafletDirective // Import the LeafletDirective here
        // import other directives as needed
    ],
})

Alternatively:

import { LeafletModule } from '@bluehalo/ngx-leaflet';

@NgModule({
    imports: [
        LeafletModule // Import the LeafletModule here
    ],
})

Create and Configure a Map

To get a basic map to work, you have to:

Apply the leaflet attribute directive (see the example below) to an existing DOM element.
Style the map DOM element with a height. Otherwise, it'll render with a 0 pixel height.
Provide an initial zoom/center and set of layers either via leafletOptions or by binding to leafletZoom, leafletCenter, and leafletLayers.

Template:

<div style="height: 300px;"
     leaflet 
     [leafletOptions]="options">
</div>

Example leafletOptions object:

options = {
	layers: [
		tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', { maxZoom: 18, attribution: '...' })
	],
	zoom: 5,
	center: latLng(46.879966, -121.726909)
};

Changes to leafletOptions are ignored after they are initially set. This is because these options are passed into the map constructor, so they can't be changed anyways. So, make sure the object exists before the map is created. You'll want to create the object in ngOnInit or hide the map DOM element with @if until you can create the options object.

Add a Layers Control

The [leafletLayersControl] input bindings give you the ability to add the layers control to the map. The layers control lets the user toggle layers and overlays on and off.

Template:

<div style="height: 300px;"
     leaflet 
     [leafletOptions]="options"
     [leafletLayersControl]="layersControl">
</div>

Component with example layersControl object:

import { LeafletDirective, LeafletLayersControlDirective } from '@bluehalo/ngx-leaflet';

@Component({
    imports: [
        LeafletDirective,
        LeafletLayersControlDirective,
    ],
})
export class MyComponent {
    protected readonly layersControl = {
        baseLayers: {
            'Open Street Map': tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', { maxZoom: 18, attribution: '...' }),
            'Open Cycle Map': tileLayer('https://{s}.tile.opencyclemap.org/cycle/{z}/{x}/{y}.png', { maxZoom: 18, attribution: '...' })
        },
        overlays: {
            'Big Circle': circle([ 46.95, -122 ], { radius: 5000 }),
            'Big Square': polygon([[ 46.8, -121.55 ], [ 46.9, -121.55 ], [ 46.9, -121.7 ], [ 46.8, -121.7 ]])
        }
    }
}

You can add any kind of Leaflet layer you want to the overlays map. This includes markers, shapes, geojson, custom layers from other libraries, etc.

Add Custom Layers (base layers, markers, shapes, etc.)

There are several different ways to add layers to the map. You can add layers (baselayers, markers, or custom layers) to the map without showing them in the layer control using the [leafletLayers] directive.

Template:

<div style="height: 300px;"
     leaflet
     [leafletOptions]="options"
     [leafletLayers]="layers">
</div>

Layers array:

layers = [
	circle([ 46.95, -122 ], { radius: 5000 }),
	polygon([[ 46.8, -121.85 ], [ 46.92, -121.92 ], [ 46.87, -121.8 ]]),
	marker([ 46.879966, -121.726909 ])
];

You can also add an individual layer to the map using the [leafletLayer] directive. Using this approach allows you to use @for and @if to control whether individual layers are added to or removed from the map.

Template:

<div style="height: 300px;"
     leaflet
     [leafletOptions]="options">
    
    @if (showLayer) {
        <div [leafletLayer]="layer"></div>
    }
</div>

Layer:

layer = circle([ 46.95, -122 ], { radius: 5000 });

Dynamically Change Map Layers

The [leafletLayers], [leafletBaseLayers], and [leafletLayersControl] inputs detect mutable changes using Angular's iterable/key-value differs. For details on performance trade-offs and how syncing works, see the API reference.

Working with Leaflet Events

Often, you'll want to make changes based on a map click or other Leaflet interaction. The ngx-leaflet plugin supports several map events and layer events as documented in the API reference.

You may occasionally need to handle events that aren't exposed through the plugin, however. When that happens, you will need to be aware of how Zones and change detection work to ensure your event handling works as expected. Take a look at A Note About Change Detection for more details. This is by design and a common thing to deal with when using third party libraries and Angular.

API

Full API documentation is in docs/API.md. It covers:

Advanced map configuration inputs ([leafletPanOptions], [leafletZoomOptions], etc.)
Dynamically changing zoom, center, and fitBounds
Layer management: [leafletBaseLayers], [leafletLayers], [leafletLayersControl], [leafletLayer]
Layer events and map events (full list)
Getting a reference to the map
A note about Angular zones and change detection

Extensions

There are several libraries that extend the core functionality of ngx-leaflet:

Cookbook

Common patterns and examples are in docs/cookbook.md, including:

Marker Setup — configuring Leaflet markers with the Angular CLI build pipeline
SSR / Server-Side Rendering — working around Leaflet's browser-only module initialization
Angular Components in Marker Popups — using createComponent() to render Angular components into Leaflet popups

Getting Help

Here's a list of articles, tutorials, guides, and help resources:

ngx-leaflet on Stack Overflow
API Reference and Cookbook — up-to-date, version-controlled docs in this repo
High-level intro to @bluehalo/ngx-leaflet (wiki — may be out of date)
Using @bluehalo/ngx-leaflet in Angular CLI projects (wiki — may be out of date)
Integrating 3rd Party Leaflet Libraries with @bluehalo/ngx-leaflet and @angular/cli (wiki — may be out of date)

Contribute

PRs accepted. Please make contributions on feature branches and open a pull request against master.

License

See LICENSE for details.

Credits

Leaflet Is an awesome mapping package.

Logo designed by @jjmhalew (#371).

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@bluehalo/ngx-leaflet

Table of Contents

Install

Usage

Import the Leaflet Stylesheet

Direct Import from HTML

Adding Styles in Angular CLI

A Note About Markers

Import LeafletDirective

Create and Configure a Map

Add a Layers Control

Add Custom Layers (base layers, markers, shapes, etc.)

Dynamically Change Map Layers

Working with Leaflet Events

API

Extensions

Cookbook

Getting Help

Contribute

License

Credits