Geolocation Fields Overview
Introduction
Ninja Geolocation adds connected location, route, validation, nearest-location, and drawing fields to Ninja Forms. A hidden Geocoder Field normally acts as the structured location record, while visible fields such as Address, Coordinates, and Map let visitors interact with that location.
The installed package determines which fields are available. A field card for a higher package may still appear in the builder as an upgrade placeholder; the placeholder does not include or enable the field's runtime functionality.
Starter Fields
Starter, Pro, and Agency include these core location fields:
| Field | Purpose | Stores an independent value? |
|---|---|---|
| Geocoder Field | Processes and stores one complete structured location. | Yes |
| Address Field | Collects an address with optional Places API (New) autocomplete. | Yes; visible address text |
| Coordinates Field | Displays or accepts latitude and longitude. | Yes; coordinate pair |
| Map Field | Displays and edits one or more connected locations on an interactive map. | Yes; map state and marker data |
| Locator Button Field | Requests the visitor's current location. | No; the Geocoder stores the result |
| Reset Location Button Field | Clears or restores one or more connected locations. | No |
Pro Fields
Pro includes every Starter field plus:
| Field | Purpose | Stores an independent value? |
|---|---|---|
| Address Validation Field | Validates an address and returns Google's standardization and validation feedback. | Yes |
| Distance & Duration Field | Calculates routed or straight-line distance between two locations. | Yes |
| Directions Field | Calculates a route with optional waypoints, map display, and instructions. | Yes |
| Directions Panel Field | Displays instructions produced by a Directions Field. | No; display only |
Pro and Agency also include the Single Submission Map and Mashup Map shortcodes.
Agency Fields
Agency includes every Pro field plus:
| Field | Purpose | Stores an independent value? |
|---|---|---|
| Nearest Locations Field | Finds, displays, and selects nearby configured destinations. | Yes |
| Nearest Locations Panel Field | Displays formatted results from a Nearest Locations Field. | No; display only |
| Drawing Tools Field | Lets visitors draw and manage markers, lines, and areas on a connected Map. | Yes |
| Drawing Shape Field | Adds a configured or JSON-defined shape to Drawing Tools. | Yes |
Setting Up a Connected Location Group
For a typical visitor-entered connected location group:
- Add one Geocoder Field to store the structured location.
- Add the Address Field from the Ninja Geolocation field group and connect it to that Geocoder. Ninja Forms' native Address field does not participate in Ninja Geolocation syncing.
- Add a Map Field and connect it to the same Geocoder.
- Optionally add Coordinates, Locator Button, or Reset Location Button Fields connected to the same Geocoder.
- Save the form and test the complete workflow on the frontend.
Each independent location needs its own Geocoder Field. A form that calculates travel from an origin to a destination therefore normally uses two Geocoders.
Ninja Geolocation supports connected fields inside Ninja Forms repeaters. Keep the related source and display fields within the same row structure so each row maintains its own location state.
Saved Values and Outputs
The Geocoder stores the normalized location record. Connected visible fields may also save their own presentation value, such as an address string, coordinate pair, map state, route result, or drawing JSON.
Directions Panel and Nearest Locations Panel are visual companions and do not store an independent value. Locator Button and Reset Location Button are interaction controls; use their connected Geocoder when you need the resulting location.
Supported ordinary Ninja Forms fields can also receive individual properties from geolocation sources through Dynamic Location Field Options.
Troubleshooting
A field appears in the builder but cannot be configured
It may be an upgrade placeholder for a feature not included in the installed package. Check the field's required plan and the package shown in the WPGeo Dashboard.
Visible location fields do not update each other
Confirm that the fields connect to the same Geocoder Field and that the form was saved after those relationships were selected.
A Ninja Forms Address field does not populate the Geocoder
Use the Address Field supplied by Ninja Geolocation. Ninja Forms' native Address field is not part of the plugin's connected geolocation system.