Animate lines with a sliding effect, with customization for color, lengths, and speed. Leverages the vanilla line-gradient property of Maplibre GL/Mapbox GL, with no other dependencies.
Check out example.html for a minimal use, and demo.html for a few possibilities.
new LineAnimation(id{, options})
Instantiates a new LineAnimation.
id: name of line layer
options: optional object of line parameters:
| key | default | function |
|---|---|---|
| dashLength | 1 | Length of the dash, as a proportion of total line geometry. Value 0-1. |
| geojson | (empty geojson) | GeoJSON object, or URL to one. Geometry should probably contain some LineString or Polygon geometry to appear properly. Can be modified later with map.getSource(id).setData(data) |
| Style | ||
| headColor | black |
Color of the leading end of dash |
| tailColor | black |
Color of the trailing end of dash. If different from head, color will interpolate naturally via line-gradient implementation |
| backgroundColor | rgba(0,0,0,0) |
Color of line in absence of dash |
| headWidth | 1 | Width of line when dash head is at the geometry's terminus (when dashProgress == 1). |
| tailWidth | 1 | Width of line when dash tail is at the geometry's terminus |
| Animation | ||
| duration | 1000 | Duration of animation, in milliseconds. Animation begins when dash head is at the geometry's beginning, and ends when tail is at the geometry terminus |
| autoStart | true |
Boolean stating whether animation starts when line is added to the map |
| loop | false |
Boolean specifying whether animation loops after the first run. If true, progress is also capped at 1 |
LineAnimation.addTo(map)
Add line layer to the map.
LineAnimation.play()
Starts/resumes the line animation. Will need this when instantiating LineAnimation with {autoStart:false}.
LineAnimation.pause()
Pauses the animation.
LineAnimation.setProgress(progress)
Set a specific progress value. To keep it at this position, recommend first pausing the animation (or instantiating it with autoStart: false).
LineAnimation consists of a single dash segment, moving in the direction of the underlying geojson line geometry. Note the tail, head, and background positions to apply color styling.
●------------LINE GEOMETRY (WEST TO EAST)--------------●
---------------- ▷▷▷▷▷▷▷▷ DASH ▷▷▷▷▷▷▷▶ ----------------
<--background--> ^tail head^ <--background-->
●------------LINE GEOMETRY (WEST TO EAST)--------------●
---------------- ▷▷▷▷▷▷▷▷ DASH ▷▷▷▷▷▷▷▶ ----------------
|----------A---------|
|------------------B------------------|
|---------------------------C--------------------------|
Dash length is expressed as a proportion of the total geometry, a value from 0 to 1. This is defined when instantiating the line layer, and does not change.
Regardless of dash length, there is a gap of length 1 between dashes. This means only one dash is visible at any given time, and in a looping animation, enters right as the previous dash exits.
Animation state is tracked predominantly as progress, which denotes the dash head's position proportionally and relative to the length of the line geometry. This value increases as the line animates, until it reaches the max value.
progress ranges from 0, where the head is right about to slide into view, to (1+dashLength), where the tail has just slid out and the next dash is about to enter. These two states bookend the cycle, and are thereby identical.