turf.bearing

What is turf.bearing?

turf.bearing takes a start and end Point and returns the initial bearing — the angle a traveller would head at the start if following a great-circle path. The result is a number in degrees from -180 to 180, measured clockwise from true north. Pass final: true to get the final bearing instead (the heading on arrival).

turf.bearing(start, end, options?) → number

Options include:

• final — boolean (default false); when true, returns the bearing you would be heading on arrival at end

When would you use turf.bearing?

Use turf.bearing to rotate icons, compute headings for moving vehicles, or orient arrows on a map. For instance, in a MapLibre animation you can update a vehicle symbol's icon-rotate property each frame based on the bearing between its previous and current positions, producing a realistic heading without manual trigonometry.

In routing and navigation UIs, combine turf.bearing with turf.distance and turf.destination to implement waypoint navigation, turn-by-turn direction cues, or compass widgets. On the server, it is handy for aligning street-view imagery or generating directional symbology in map-tile pipelines.

undefined

FAQs

What is the difference between initial and final bearing?

On a great-circle route, the heading changes continuously as you travel. Initial bearing (default) is the direction at the start; final bearing (final: true) is the direction on arrival. For short distances the two are nearly identical; on intercontinental routes they can differ by tens of degrees.

How do I normalise the result to 0–360?

turf.bearing returns -180 to 180. Convert with (bearing + 360) % 360 when you need a compass-style heading. This is common when binding the result to icon rotation in MapLibre or Mapbox symbol layers.

Can I get a rhumb-line bearing instead?

Yes — use turf.rhumbBearing. A rhumb line is a constant-heading path (like a ship following a single compass bearing), which differs from the great-circle geodesic. Use rhumb bearings for maritime and navigation-style displays and geodesic bearings for aviation or minimum-distance routing.

How do I install just bearing?

npm install @turf/bearing. It depends only on @turf/helpers and @turf/invariant, making it a safe, small dependency for interactive map projects.