Neoplastic Plasma Medusa

    TypeScript icon, indicating that this package has built-in type declarations

    1.0.4 • Public • Published

    Route Directions component

    Route Directions is an integration component that lets you add a User Interface for Geoapify Routing API functionality to your website. RouteWaypoints lets you easily define route waypoints, select and save routes, choose your routing mode (car, bicycle, motorbike), and set your preferred route options (avoid highways, tolls, ferries).

    Live Demo

    Add Route Directions to your website

    The Route Directions component is flexible and straightforward to use. Here's how to get started with it.

    Step 0. Get a Geoapify API key

    The component uses Geoapify Geocoding API and Routing API to get waypoints and calculate routes. You need to register for a Geoapify API key first - Sign Up.

    Geoapify offers a Free plan that includes up to 3,000 API requests per day. You can upgrade to a paid plan that better fits your needs at any time.

    Step 1. Install or link Route Directions package

    Option 1

    The Driving Directions component is available as a package in NPM. You can install it with the npm command to your project:

    npm i @geoapify/route-directions

    Then import the styles file. For example, in your styles file, add:

    @import '~@geoapify/route-directions/styles/styles.css';

    Option 2

    As an alternative, you can add a library link to your HTML page:

    <script src="^1/dist/index.js"></script>

    This can be especially useful when you use a CMS (WordPress, Hubspot, Joomla, etc.) to build your website. Then, add the component styling as an appropriate HTML tag, like so:

    <link rel="stylesheet" href="^1/styles/styles.css" />

    Step 2. Add HTML-container

    The Routing component needs to be put inside an HTML container in which all the controls will be placed. This can be a simple div element with some unique id, so you can access it from a document object:

    <div id="route-directions"></div>

    The control will take up the entire width of the container.

    Step 3. Add Route Directions to the provided container

    Then you would create a RouteDirections object like this:

    const routeDirections = new RouteDirections(document.getElementById("route-directions"), GEOAPIFY_API_KEY);

    or like this, if you want to pass custom options object:

    const routeDirectionOptions = {
    const geocoderOptions = {
    const routeDirections = new RouteDirections(document.getElementById("route-directions"), GEOAPIFY_API_KEY, routeDirectionOptions, geocoderOptions);

    When working with ES6 modules, you need to import the object type:

    import { RouteDirections, RoutingOption, TravelMode } from '@geoapify/route-directions';

    Route Directions options

    Here are the options you can specify when creating a route directions object:

    Option Type Default value Description
    mode walk, hike, scooter, motorcycle, drive, light_truck, medium_truck, truck, bicycle, mountain_bike, road_bike, bus drive Travel or transportation mode
    waypoints array of {lat: number, lon: number, address: string} [{}, {}] Waypoints containing geographical coordinates and address information
    avoidHighways boolean false Avoid highways when calculating the route
    avoidTolls boolean false Avoid tolls when calculating the route
    avoidFerries boolean false Avoid ferries when calculating the route
    elevation boolean false Include elevation data and ranges to the route
    units metric, imperial metric Distance units
    lang bg, ca, cs, da, de, el, en, es, et, fi, fr, hi, hu, it, ja, nl, pl, pt, ro, ru, sk, sl, sv, tr, uk en Language
    noStopover boolean false Don't let to add more than two waypoints
    supportedModes array of [ walk, hike, scooter, motorcycle, drive, light_truck, medium_truck, truck, bicycle, mountain_bike, road_bike, bus] [walk, bicycle, drive, medium_truck] Travel modes to be shown on the control
    supportedOptions array of [tolls, ferries, highways, units] [] Options to be shown on the control
    calculateRouteTrigger auto, buttonClick, functionCall auto Defines how the route calculation is triggered: auto - the route calculated automatically when waypoints or options are changed; buttonClick - the route calculation is triggered when the "Calculate" button is clicked; functionCall - the route calculated when the calculate() method is called
    labels { [ key: string ]: string } Check "Localization options" The control includes labels for a better user experience. You can customize/localize those labels by overriding the default ones.
    debounceDelay number 2000 Delay (in milliseconds) after the last user interaction is used as a timeout for the route calculation. This helps to avoid unnecessary API calls when calculateRouteTrigger is auto.

    In addition, you can provide geocoding options for waypoint inputs. For example, you can specify language, preferred locations, and filters. Learn more about Geoapify Geocoder Option on the @geoapify/geocoder-autocomplete page.

    Routing for walking, hiking, cycling modes

    const routeDirections = new RouteDirections(document.getElementById("route-directions"), apiKey, {
      mode: 'walk',
      supportedModes: ['walk', 'hike', 'bicycle', 'mountain_bike', 'road_bike']

    Predefine waypoints

    const routeDirections = new RouteDirections(document.getElementById("route-directions"), apiKey, {
      waypoints: [
        { address: "Paris, France" },
        { address: "Lyon, France" },
        { address: "Grenoble, France" },

    Add options and the "Calculate button"

    const routeDirections2 = new RouteDirections(document.getElementById("route-directions"), apiKey, {
      supportedOptions: ['highways', 'tolls', 'ferries', 'units'],
      calculateRouteTrigger: 'buttonClick'

    Route Direction methods

    The Driving Directions control provides methods that help you integrate better the Routing API with other objects on the website. For example, you can use a map to show your route, or you can use buttons to start or stop directions:

    Method Description Example
    getOptions() Returns the current RouteDirections options object const option = routeDitections.getOptions();
    addLocation(lat: number, lon: number, address?: string) Add a new location to an existing but empty waypoint. The method was handy to define locations by clicking on a map. routeDitections.addlocation(, event.lon);
    calculate() Calculate the route. This lets you trigger the route calculation outside the control. routeDitections.calculate();
    on(operation, callback) Add a callback on an operation. Possible operations - modeChanged, optionChanged, waypointChanged, routeCalculated. routeDirections.on('routeCalculated', (route: GeoJSON.Feature) => { ... });
    off(operation, callback) Remove a callback.'routeCalculated', myCallback);

    Add a callback for the calculated route

    const routeDirections = new RouteDirections(document.getElementById("route-directions"), apiKey);
    routeDirections.on('waypointChanged', (waypoint, reason) => {
    routeDirections.on('modeChanged', (mode: TravelMode) => {
    routeDirections.on('optionChanged', (option: RoutingOption) => {
    routeDirections.on('routeCalculated', (geojson: any) => {

    Add a waypoint location on a Leaflet map click

    map.on('click', (event) => {
      routeDirections.addLocation(, event.latlng.lng)

    Customize and localize the control

    You can customize and localize the labels found on the RouteDirections controls by providing the custom "labels" object in the options object:

    Label Default value
    avoid "Avoid:"
    units "Units:"
    addDestination "Add destination"
    avoidTolls "Tolls"
    avoidFerries "Ferries"
    avoidHighways "Highways"
    unitsMiles "Miles"
    unitsKilometers "Kilometers"
    calculateButton "Calculate"
    noRouteFound "No route found"
    warning.min2Waypoints "Choose at least two waypoints to calculate a route"
    walk "Walk"
    hike "Hike"
    scooter "Scooter"
    motorcycle "Motocycle"
    drive "drive"
    light_truck "Van"
    medium_truck "Delivery truck"
    truck "Truck"
    bicycle "Bicycle"
    mountain_bike "Montain bicycle"
    road_bike "Road bicycle"
    bus "Bus"

    Localize the control

    const routeDirections2 = new RouteDirections(this.container2.nativeElement, apiKey, {
      labels: {
        "avoid": "Избегать:",
        "addDestination": "Добавить новый пункт назначения",
        "avoidTolls": "Платные дороги",
        "avoidFerries": "Паромы",
        "avoidHighways": "Автострады",
        "calculateButton": "Расчитать",
        "noRouteFound": "Путь не найден"

    Style the controls

    You can customize the styling of the control. There are the CSS classes you can use for the customization:

    CSS class Description
    .geoapify-route-directions-add-destination Add destination button
    .geoapify-route-directions-mode-button Mode button
    .geoapify-route-directions-message Error message
    .geoapify-route-directions-generate-button Calculate button


    npm i @geoapify/route-directions

    DownloadsWeekly Downloads






    Unpacked Size

    248 kB

    Total Files


    Last publish


    • geoapify