Gravity Forms Advanced Autocomplete Field

Video walkthrough

1:16

Add Autocomplete to Gravity Forms: Type-Ahead Suggestions, Single or Multi-Select
A short walkthrough: install the add-on, add the Autocomplete field, pick where suggestions come from, then turn on multiple selections and set the record limit and minimum letters. Watch on YouTube

The Gravity Forms Advanced Autocomplete Field adds a new Autocomplete field type to Gravity Forms. As your visitor types, the field shows a short list of matching suggestions pulled from a source you choose: a comma-separated list you type in, a column of a MySQL table, an imported JSON file, a WordPress post type, or a JSON file hosted at a URL. You decide whether visitors may only pick values from that source or may also type their own, whether they can pick one value or several, and whether the field uses the classic suggestion list or a Select2 tag layout.

This guide walks through every setting the add-on provides, explains exactly how each data source behaves on the front end and during validation, and closes with developer snippets and a troubleshooting checklist. Everything described here is based on version 2.2.14 of the add-on.

Step 1: Activate Your License Key

Go to Forms → Settings → Autocomplete Field. The page contains a single Gravity Extra License panel. Paste your key into the License Key box and click Active License. When the key is accepted, a green check mark appears inside the box, the box becomes read-only and the button changes to Deactive License, which you can use later to move the license to another site.

Your license key is listed in your GravityExtra account: log in at gravityextra.com, open My Account and click the License keys tab. The View Instructions link on the settings page shows the same steps. This settings page holds only the license; all autocomplete options are configured per field in the form editor.

Step 2: Add the Autocomplete Field to Your Form

Open your form in the Gravity Forms editor. In the Add Fields panel, expand Advanced Fields and drag Autocomplete onto the form (or type “Autocomplete” in the field search box). The new field is labelled “Autocomplete” by default; change the label on the General tab like any other field.

Select the field and open its Advanced tab. Directly below Admin Field Label you will find the Autocomplete Settings block, followed by the behaviour options described in Step 4.

Step 3: Choose Where the Suggestions Come From

The Please Select Source Type dropdown offers five sources. New fields start with Input String. Only the inputs for the selected source are shown.

Input String

Type your suggestions into the text area, separated by commas, for example Germany, France, Japan. Spaces around the commas are ignored. This is the quickest option for short, stable lists such as countries, departments or product names.

MySQL Database Table

Enter a Table Name and a Column Name from your WordPress database. Every value in that column becomes a suggestion. When the suggestions are loaded, the add-on accepts the table name either exactly as typed or with your WordPress table prefix added. The value check on submission, however, uses the table name exactly as you typed it, so always enter the full name including the prefix (for example wp_posts, not posts).

Imported JSON File

Click Choose File and select a .json file. The file is uploaded to your Media Library straight away and its name appears under Existing file; any other file type is rejected with a message. To switch to a different list later, simply choose a new file. Use the structure below: each entry has a label (what visitors see in the suggestion list) and a value (what is saved in the entry). If no file has been uploaded, the add-on falls back to its built-in list of 245 countries, labelled by country name with the two-letter country code as the value.

[
  { "label": "Germany", "value": "DE" },
  { "label": "Japan", "value": "JP" },
  { "label": "Vietnam", "value": "VN" }
]

Post Type

Choose a Post Type (Posts, Pages and every public custom post type registered on your site) and a Post Field: post_title, post_author or post_date. Suggestions are built from all published items of that type, so a new product, course or location appears in the list as soon as you publish it. Note that post_author returns the numeric author ID, not the author name, and post_date uses the Y-m-d H:i:s format. For most forms, post_title is the field you want.

URL JSON

Paste the address of a JSON file into URL JSON File. The file must use the same label/value structure as an imported file. Your server downloads the file each time the form is displayed and again when the form is submitted, so a list you update at that address is picked up without editing the form. Make sure the URL is publicly reachable from your server and responds quickly, because a slow response delays the form.

Data Source Comparison

Step 4: Configure How Visitors Pick Values

Below the source settings, the Advanced tab contains five options that control the visitor experience.

Record Limit and Minimum Input Letters apply to the standard suggestion list. When Select2 Layout is enabled, Select2 shows its own searchable list of all available values instead.

Standard Gravity Forms Settings That Also Apply

• Required, Description, Placeholder, Custom CSS Class, Field Size and Visibility work as they do on a normal text field. The restricted-mode message is set by the add-on; see the developer section to change its wording.
• Default Value pre-fills the field. With “Select multiple value” on, separate several defaults with commas.
• Allow field to be populated dynamically lets you fill the field from a query string parameter or a PHP filter (see the developer section).
• Enable Autocomplete further down the Advanced tab is a separate Gravity Forms core option for the browser’s own autofill. It does not control the add-on’s suggestions; the Autocomplete field always switches browser autofill off so it does not cover the suggestion list.

What Visitors See on the Front End

In the standard layout, suggestions appear under the field as the visitor types. Matching is case-insensitive and finds the typed text anywhere in a suggestion, so typing “Ger” offers Algeria, Germany and Nigeria. Clicking a suggestion (or using the arrow keys and Enter) fills the field. With “Select multiple value” on, each selection is appended to the field followed by a comma, ready for the next one.

With Select2 Layout and “Select multiple value” enabled, every choice becomes a tag that can be removed with its small x, and the search box filters the remaining options as the visitor types.

Restricted Mode (Other Values Disabled)

When “Enable the ability to enter other values than source” is off, the field protects your data in two ways. While typing, characters that do not appear in any suggestion are blocked and the message “Please enter a valid value.” appears under the field. On submission, the add-on checks every value (each comma-separated item for multi-value fields) against the source, and if one is not found the form is returned with the same message. Values that only contain allowed letters but are not in the list, such as “Atlantis” in a country field, are caught by this server-side check.

Data Handling & Privacy

• Your suggestion list is public. To show suggestions instantly, the complete list for each Autocomplete field is included in the page sent to the visitor’s browser. Anyone can view it in the page source. Never point the MySQL or Post Type source at private data such as user emails, order details or unpublished content.
• No lookup service. The add-on does not send what visitors type to any third party; matching happens in the visitor’s browser. Your server only makes an outgoing request when it downloads a URL JSON file.
• One external script. On pages that contain an Autocomplete field, the visitor’s browser loads the jQuery UI library (version 1.13.2) from code.jquery.com. If your privacy policy lists third-party resources, include this one.
• Plain text storage. The selected value is stored in the entry as ordinary text, so it appears in entry lists, exports, merge tags and notifications like any text field.
• Imported files are public files. An imported JSON file is stored in your Media Library, which means it has a public URL. Treat its contents as public.

Using the Field with Conditional Logic

The Autocomplete field supports conditional logic in both directions: it can be shown or hidden by rules, and other fields, notifications and confirmations can use its value in their rules. It is also available in notification routing. A few practical patterns:

• Route enquiries by country: in a notification’s Send To section, choose Configure Routing and send the email to your EU team when the country field “is” Germany, France or another EU country, and to your US team when it “is” United States.
• Ask follow-up questions: show a “WordPress version” field only when a multi-value skills field “contains” WordPress. Use “contains” rather than “is” for multi-value fields, because the saved value holds every selection in one comma-separated text.
• Different confirmations per product: with the Post Type source on your products, show a product-specific confirmation message when the field “is” a particular product title.
• Keep rules reliable: conditional rules compare against the saved value. For Imported JSON and URL JSON sources, that is the value (for example DE), not the label (Germany).

Developer Reference

The add-on does not define its own PHP filters or actions. Because the Autocomplete field is a regular Gravity Forms field with the type autocomplete, the standard Gravity Forms hooks work with it. Add these snippets to your child theme’s functions.php or a code snippets plugin.

Pre-fill the Field Dynamically

Tick Allow field to be populated dynamically on the field’s Advanced tab and enter a parameter name, for example preferred_country. You can then pass ?preferred_country=Germany in the page URL, or set the value in PHP:

// Pre-fill the Autocomplete field whose parameter name is "preferred_country".
add_filter( 'gform_field_value_preferred_country', function( $value ) {
    return 'Germany';
} );

Customise the Restricted-Mode Validation Message

The add-on performs its source check on the gform_field_validation filter at the default priority of 10. A filter at a later priority can replace the message it sets:

// Friendlier message when a value is not in the Autocomplete source.
add_filter( 'gform_field_validation', function( $result, $value, $form, $field ) {
    if ( $field->type === 'autocomplete'
        && ! $result['is_valid']
        && $result['message'] === 'Please enter a valid value.' ) {
        $result['message'] = 'Please choose one of the suggested options.';
    }
    return $result;
}, 20, 4 );

Style the Suggestion List

The standard suggestion list is a jQuery UI menu (.ui-autocomplete) and the field wrapper carries the class .ginput_container_autocomplete, so you can match the list to your theme with a few lines of CSS (Appearance → Customize → Additional CSS):

/* Rounded suggestion list with a scroll bar for long lists */
.ui-autocomplete {
    max-height: 260px;
    overflow-y: auto;
    border-radius: 8px;
}
.ui-autocomplete .ui-state-active {
    background: #00c48d;
    border-color: #00c48d;
    color: #ffffff;
}

What’s new in version 2.2.15

Version 2.2.15 adds five features to the Autocomplete field. Forms built with an older version keep working as before: nothing changes until you turn a new option on.

1. Cascading (dependent) fields

A field can show only the suggestions that belong to the value chosen in another field. Example: pick a country in the first field, and the city field suggests only that country’s cities.

1. Add the parent field (any field that holds a value, for example another Autocomplete field or a Drop Down).
2. Add the Autocomplete field for the children and choose a Source Type: MySQL Database Table, Post Type or Taxonomy Terms.
3. Open Advanced, tick Enable parent field dependency and pick the Parent field.
4. Tell the field how the parent value is matched:
   • MySQL Database Table: enter the Parent value column (the column that holds the parent value, for example country).
   • Post Type: choose Parent filter = Post meta and enter the custom field key (for example region), or Taxonomy term ID and enter the taxonomy (for example category).
   • Taxonomy Terms: nothing to enter. The parent value can be a term ID, name or slug; the field suggests the direct child terms of that term.

When the parent value changes, the child field is cleared. On submit, the add-on checks again on the server that the child value belongs to the parent value; if it does not, the visitor sees “Please select a value valid for the selected parent field.” (unless Enable Other Values is on).

2. Connected field auto-fill

When a visitor picks a suggestion, other fields of the form can be filled from the same record. Example: pick a city and the “City code” field is filled with that city’s code.

1. Use the MySQL Database Table, Post Type or Taxonomy Terms source.
2. In Advanced, tick Enable Connected Field Auto-Fill.
3. For each row choose the form field to fill and the source property: a table column, a post field (title, content, excerpt, author, date, status, slug), a term property (name, slug, description, ID, taxonomy), or a custom field: choose Post Meta / Term Meta and type the meta key. Use the + and − buttons to add or remove rows.

Only the columns and properties you map are sent to the browser. Columns that look like passwords, tokens or keys (for example user_pass, secret_token, api_key, post_password) are never sent, even if they are mapped.

3. Show a label, store a different value

Visitors see a readable label and the entry stores another value. Example: the field shows “Lyon” and saves FR-69; or it shows a post title and saves the post ID.

1. In Advanced, tick Store Separate Value (Label / Value Decoupling).
2. Choose the Value column: a table column (MySQL), a post field such as Post ID (Post Type), a term property such as Term ID (Taxonomy Terms), or User ID (WordPress User). For JSON files and JSON URLs the item’s value is stored and its label is shown.

The label is what the visitor reads; the value is what the entry, notifications and merge tags contain. Tip: write conditional logic rules for other fields with the label (the browser compares what is shown) and rules used after submission (notifications, confirmations) with the stored value.

4. Remote REST API source

Suggestions can come from your own or a third-party JSON API while the visitor types.

1. Choose Source Type = Remote REST API.
2. Endpoint URL: the address of the search, with {search_term} where the typed text goes, for example https://api.example.com/cities?q={search_term}.
3. Authentication: None, Bearer token (sent as Authorization: Bearer …) or API key header (enter the header name, for example X-API-Key, and the key). The token or key is sent by your server only; it never appears in the page.
4. Results path: where the list is in the answer, for example results or data.items (leave empty if the answer is the list itself).
5. Label path and Value path: the property of each item to show and to store, for example title and id (results[].title is accepted too). If the value path is empty, the label is stored.

Notes: each search term is asked once and the answer is cached for 5 minutes; requests time out after 10 seconds; only public http/https addresses are allowed (no local or private network addresses). On submit, the stored value is checked against the API again.

5. Select2 improvements

With Enable Select2 on, cascading fields and Remote REST API fields now search through the server as you type (Select2 AJAX). Select2 boxes use the full width of the field. Labels are always shown as plain text.

Fixed: a Required field with Enable Other Values accepts a value the visitor types in.

Also new: Taxonomy Terms and WordPress User sources

• Taxonomy Terms: suggestions are the terms of a public taxonomy (for example Categories).
• WordPress User: suggestions are the display names of users who can write posts (staff). Usernames and e-mail addresses are never shown. With Store Separate Value the user ID is stored.

Troubleshooting & FAQ

More Screenshots of the Field Settings

These close-ups show individual settings from the field editor in more detail.

Related Resources & Live Demonstration