# 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](https://leafletjs.com/) itself, and [Leaflet GeometryUtil](https://github.com/makinacorpus/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: ```javascript import 'leaflet-arrowheads'; ``` ### Without ES6 Imports Grab the [source file](https://github.com/slutske22/leaflet-arrowheads/blob/master/src/leaflet-arrowheads.js) 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](https://github.com/makinacorpus/Leaflet.GeometryUtil), which must come _after_ a link to the leaflet source. Your main project javascript will come after this, like so: ```html ``` ## Usage Arrowheads can be applied to any polyline, whether unisegmental, multisegmental, continuous, or discontinuous: ```javascript 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: ```javascript myVector.addTo(map) or myVector.remove() ``` If you need to access the arrowheads directly, you can call the `.getArrowheads()` method on your polyline. ```javascript myVector.getArrowheads(); // returns the arrowheads polyline object myVector.getArrowheads().remove(); // removes arrowheads from map ``` Arrowheads can also be deleted from their parent polyline entirely: ```javascript myVector.deleteArrowheads(); ``` Arrowheads can take a configuration object as its argument: ```javascript var myVector = L.polyline([ coords ]).arrowheads({ }); ``` You can also use arrowheads on a GeoJSON that contains `LineString` or `MultiLineString` features by adding it as an option: ```javascript var myGeoJson = L.geoJSON(geoJsonData, { arrowheads: { } }); ``` ## Options Arrowheads offers a variety of options for rendering and styling arrowheads. See the options table below.

Arrowheads inherit all options from [L.Path](https://leafletjs.com/reference-1.6.0.html#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 Number | String
( Meters | Percent or Pixels ) 		'15%' Determines the size of the arrowhead. Accepts three types of values:
  • A number will set the size of the arrowhead to that number of meters
  • 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](https://codesandbox.io/s/leaflet-arrowheads-ts-example-kwonf). 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](https://github.com/bbecquet/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.