leaflet-arrowheads

Leaflet-Arrowheads is a small plugin for leaflet to quickly draw arrowheads on polylines for vector visualization.

👀 DEMO 👀

Installation

Leaflet-Arrowheads compatible with leaflet 1.7.1+. It has 2 dependencies: Leaflet itself, and Leaflet GeometryUtil.

You can use npm to install leaflet-arrowheads:

npm install leaflet-arrowheads --save

Then you can simply import its content into your project:

import 'leaflet-arrowheads';

Without ES6 Imports

Grab the source file and include it in your project. You can include the source file in your header, but it must come after a link to Leaflet GeometryUtil, which must come after a link to the leaflet source. Your main project javascript will come after this, like so:

<head>
	<script src="https://unpkg.com/[email protected]/dist/leaflet.js"></script>
	<script src=".../scripts/leaflet.geometryutil.js"></script>
	<script src=".../scripts/leaflet-arrowheads.js"></script>
	<script src=".../yourProjectScript.js" defer></script>
</head>

Usage

Arrowheads can be applied to any polyline, whether unisegmental, multisegmental, continuous, or discontinuous:

var myVector = L.polyline([coords]).arrowheads();

Arrowheads will be added to your polyline and will automatically be added to and removed from the map when you call add and remove methods on your polyline:

myVector.addTo(map) or myVector.remove()

If you need to access the arrowheads directly, you can call the .getArrowheads() method on your polyline.

myVector.getArrowheads(); // returns the arrowheads polyline object
myVector.getArrowheads().remove(); // removes arrowheads from map

Arrowheads can also be deleted from their parent polyline entirely:

myVector.deleteArrowheads();

Arrowheads can take a configuration object as its argument:

var myVector = L.polyline([ coords ]).arrowheads({ <Options> });

You can also use arrowheads on a GeoJSON that contains LineString or MultiLineString features by adding it as an option:

var myGeoJson = L.geoJSON(geoJsonData, { arrowheads: { <Options> } });

Options

Arrowheads offers a variety of options for rendering and styling arrowheads. See the options table below.

Arrowheads inherit all options from L.Path. Arrowheads also inherit all options from their parent polylines, except fill, fillOpacity, and smoothFactor. These can be changed manually when defining the arrowheads' options, but changing smoothFactor will result in improperly rendered arrows.

Option	Type	Default	Description
yawn	Number ( Degrees )	60	Defines the width of the opening of the arrowhead, given in degrees. The larger the angle, the wider the arrowhead.
size	String ( Meters or Percent or Pixels )	'15%'	Determines the size of the arrowhead. Accepts three types of values: A string value which is a number with the suffix 'm' ( '1.5m', '20m', '250m', etc. ) will render arrows whose size is that many metres. Ideal for maps with low variance in zoom levels. A string value which is a number with a percent sign ( '15%', '20%', '25%', etc. ) will render arrows whose size is that percentage of the size of the parent polyline. If the polyline has multiple segments, 'size' will take the percent of the average size of the segments. A string value which is a number with the suffix 'px' ( '20px', '25px', '30px', etc. ) will render an arrowhead whose size stays at a constant pixel value, regardless of zoom level. Will look strange at low zoom levels or for smaller parent vectors. Ideal for larger parent vectors and at higher zoom levels.
frequency	Number \| String ( Number of arrowheads \| Meters, Pixels, 'allvertices', 'endonly' )	'allvertices'	How many arrowheads are rendered on a polyline. 'allvertices' renders an arrowhead on each vertex. 'endonly' renders only one at the end. A number value renders that number of arrowheads evenly spaces across the polyline. A string value with suffix 'm' (i.e. `'100m'`) will render arrowheads spaced evenly along the polyline with roughly that many meters between each one. A string value with suffix 'px' (i.e. `'30px'`) will render arrowheads spaced evenly with roughly that many pixels between each, regardless of zoom level.
proportionalToTotal	Boolean	false	Only relevant when `size` is given as a percent. Useful when `frequency` is set to `'endonly'`. Will render the arrowhead(s) with a size proportional to the entire length of the multi-segmented polyline, rather than proportional to the average length of all the segments.
offsets	Object `{ start?: string; end?: string }`	undefined	Enables the developer to have the arrowheads start or end at some offset from the start and/or end of the polyline. This option can contain one or both `start` and `end` properties. Each must be a string defining the size of the offset in either meters or pixels (i.e. `'100m'`, `'15px'`, etc.)
perArrowheadOptions	Function `(i: number) => ArrowheadOptions`	undefined	Enables the developer to customize arrowheads on a one-by-one basis. Must be in the form of a function of `i`, which is the index of the arrowhead as it is rendered in the loop through all arrowheads. Must return an object that is options object, the same type of options object that is the agrument for `.arrowheads({ <Options> })`. Cannnot account for `frequency` or `proportionalToTotal` from within the `perArrowheadOptions` callback. See examples for details.

There are many different ways to combine these various options. See examles below. Many combinations are untested, so if you encounter a problem, open and issue or a PR.

Examples

A demo project is available for viewing at https://codesandbox.io/s/leaflet-arrowheads-example-zfxxc. The web page alone without the code: https://zfxxc.csb.app/

There is also a small typescript example sandbox here.

Polylines in this demo have popups which each contain the code for that polyline. Click around, and feel free to look through the codesandbox for more detail.

Yawn Options
L.polyline([]).arrowheads() (Standard option gives 60 degree yawn)		L.polyline([]).arrowheads({ yawn: 90 })
L.polyline([]).arrowheads({ yawn: 40 })		.arrowheads({ yawn: 40, fill: true })

Color and Fill Options
L.polyline([]).arrowheads() (Standard options makes arrowheads a vector with same color as parent)		L.polyline([]).arrowheads({ fill: true })
L.polyline([]).arrowheads({ color: 'black' })		L.polyline([],{ color: 'black' }) .arrowheads({ fill: true })
L.polyline([]).arrowheads({ color: 'black' })		L.polyline([]).arrowheads({ fill: true, color: 'black' fillColor: 'green' })

Size Options
Setting size to a number or percent will give you a fixed size arrowhead (in meters or percent of the size of the segment, respectively), regardless of zoom size. See the frequency examples below for a better idea.
L.polyline([coords]).arrowheads({size: '20px', fill: true})

Frequency Options

Standard option:

L.polyline([coords], { smoothFactor: 5 })
   .arrowheads({ frequency: 'allvertices' });

L.polyline([coords])
   .arrowheads({ 
      frequency: 'endonly', 
      size: '50%' 
   });

20 arrowheads evenly distributed

L.polyline([coords]).arrowheads({ frequency: 20 });

Arrowheads every ~500 m evenly distributed

L.polyline([coords]).arrowheads({ frequency: '500m' });

Arrowheads every 50px regardless of zoom

L.polyline([coords])
   .arrowheads({ 
      frequency: '50px', 
      size: '12px'
   });

Offset Options

L.polyline([coords])
   .arrowheads({ 
      frequency: 'endonly',
      size: '30px',
      offsets: { end: '15px' }
   });

L.polyline([coords])
   .arrowheads({ frequency: 20,
      size: '300m',
      offsets: { end: '15px' }
   });

L.polyline([coords1, coords2])
   .arrowheads({ frequency: '1000m',
      size: '300m',
      offsets: { 
         start: '5000m', 
         end: '15px' 
      }
   });

Per-Arrowhead Options

L.polyline([coords], { color: 'black', weight: '2' })
   .arrowheads({
      frequency: '500m',
      color: 'darkblue',
      perArrowheadOptions: (i) => ({
         size: i % 3 === 0 ? '30%' : '15%',
         color: i % 2 === 0 ? 'red' : undefined,
         fill: (i + 1) % 4 === 0,
         yawn: (i + 1) % 4 === 0 ? 35 : undefined,
      }),
   });

L.polyline([coords])
   .arrowheads({ 
      size: '20px',
      fill: true,
      yawn: 30,
      frequency: 20,
      perArrowheadOptions: (i) => ({
         color: `rgba(150, 20, ${0 + 20 * i}, 1)`,
      }),
   });

Alternatives

After writing this plugin I discovered Leaflet.PolylineDecorator. This offers some great methods to decorate your lines, potentially with arrowheads.

Limitations

Arrowheads sometimes look like they're in slightly the wrong orientation in areas of high curvature. This is because of the way leaflet-arrowheads chooses and interpolates the points that it uses to calculate bearings. This may be able to be improved. Feel free to contribute / open a PR.

scavanger / leaflet-arrowheads-cjs Goto Github PK