Documentation

Directions Field

Last modified: September 11, 2026

Introduction

The Directions Field calculates a route between an origin and destination, with optional waypoints. It can save distance, duration, route legs, and step-by-step instructions, and can draw the route on a linked Map Field.

Use Google Routes API for road routing and travel time. Use Straight-Line (Haversine) when you only need the direct geographic distance between points.

Gravity Forms Directions Field
Directions Field front-end output.

Requirements

  • Two Geocoder Fields for the origin and destination.
  • The Google Routes API enabled for road routes, travel time, route maps, and step-by-step instructions.
  • An optional Map Field to draw the route.
  • An optional Directions Panel Field to display route steps.

Configuring the Directions Field

Directions field options
Directions Field settings.

1. Travel Calculation Method

  • Google Routes API: Calculates a road route, distance, duration, legs, and steps (Default).
  • Straight-Line (Haversine): Calculates direct geographic distance without roads, traffic, duration, or step-by-step directions.

2. Trigger Method

How Should Directions Be Triggered?

  • Manually (Using a Button): Display buttons for the visitor to calculate or clear the route (Default).
  • Automatically (When Fields Change): Recalculate when a linked route point or supported travel control changes.

Get Directions Button Text

Customize the manual calculation button (Default Value: Get directions).

Clear Directions Button Text

Customize the button that clears the route (Default Value: Clear directions). Leave it blank to hide the clear button.


3. Directions Source and Destination

Origin Field (Geocoder)

Select the Geocoder Field that represents the starting location.

Destination Field (Geocoder)

Select the Geocoder Field that represents the ending location.

Waypoint Fields (Optional)

Select one or more Geocoder Fields that the route should visit between the origin and destination. Waypoints apply to Google Routes API calculations.


4. Travel Preferences

Measurement System

  • Imperial (Miles) (Default).
  • Metric (Kilometers).

Travel Mode

Select Driving, Walking, Bicycling, or Public Transit (Default: Driving).

Travel Mode Field

Optionally select a Dropdown or Multiple Choice field that lets the visitor choose the travel mode. Its choices should use supported travel-mode values.

Routing Preference

  • Traffic Unaware (Shortest Distance) (Default).
  • Traffic Aware: Uses current traffic conditions where supported.
  • Traffic Aware Optimal: Uses Google’s more complete traffic-aware calculation.

Route Restrictions

Use Avoid Ferries, Avoid Highways, and Avoid Tolls when applicable. Google may still use a restricted route type when no reasonable alternative is available.


5. Travel Date and Time Settings

These settings apply to Google Routes API calculations.

Travel Time Mode

  • Leave Now (Default).
  • Leave At Specific Time.
  • Arrive By Specific Time.

Travel Time Mode Field

Optionally let a front-end field override the default time mode.

Default Travel Date and Travel Date Field

Set an administrator-defined date or select a Date Field that lets the visitor provide it.

Default Travel Time and Travel Time Field

Set an administrator-defined time or select a Time Field that lets the visitor provide it.


6. Display Settings

Map Field for Displaying Route

Select the Map Field where the route line should appear.

Polyline Appearance

Customize the route line with Google Maps polyline properties (Example: strokeColor:'#0088FF',strokeWeight:6,strokeOpacity:0.6).

Directions Panel Output

Select a Directions Panel Field for step-by-step route instructions. This is available with Google Routes API routing, not Straight-Line mode.

Saved Data and Merge Tags

The Directions Field saves structured route data, including total distance, duration when available, route legs, addresses, route geometry, travel mode, and related metadata. The entry detail view displays a readable route summary.

The normal field merge tag produces HTML output. Add a supported modifier when a different format is needed:

  • {Directions:FIELD_ID:distance}
  • {Directions:FIELD_ID:duration}
  • {Directions:FIELD_ID:text}
  • {Directions:FIELD_ID:json}
  • {Directions:FIELD_ID:link}
  • {Directions:FIELD_ID:legs}

Setting Up and Using the Directions Field

  1. Add origin and destination Geocoder Fields and their visible Address, Coordinates, or Map inputs.
  2. Add the Directions Field and choose the two Geocoders.
  3. Select the calculation and trigger methods.
  4. Configure travel, date/time, and display options.
  5. Preview the form, calculate a route, submit the entry, and verify the saved route output.
menu-circle