Lookup

Use Lookup fields to dynamically populate field options and values with the data from submitted entries. Lookup fields can be used for several types of dynamic field relationships. You may use them to:

• Retrieve submitted values and use them as options in a dropdown, radio, or checkbox field, or for display only.
• Set up cascading field options. This is perfect for country/state/city or year/make/model fields where the available options are filtered by the value selected in a prior field.
• Filter down to a price or final value. Allow the user to select options from Lookup fields which will ultimately display a final price or value in a text/number field.
• Dynamically populate field values. Allow users to select or enter a value in a Lookup field which will populate fields in the form with values from the same entry.

If you want to learn more about the differences between a Dynamic field and a Lookup field, please click here.

Standard field options

A Lookup field has the following standard options:

• Field type
• Required
• Unique
• Read Only
• Field key
• CSS layout classes
• Label position
• Field size
• Dynamic default value
• Visibility
• Conditional logic

Field-specific options

Display lookup fields

Display the value submitted in a Lookup field in a form's confirmation message, email, or View. Just insert [x], where x is the ID or key of the Lookup field.

Set up a single Lookup field

If you would like to add an individual Lookup field to your form so that you can use submitted values as options, follow the directions below.

1. Create a new form or go into an existing form where you would like to add a Lookup field.
2. Add a Lookup field to your form. By default, a Lookup field will display as a dropdown, but you can change Display as to Single line text, Radio button or Checkbox if you would prefer.
   
3. Set up your Lookup field to Get options from: any form/field on your site.
   
4. In the field options, select the Option order that you would like. You can display options in ascending order (A-Z), descending order (Z-A), or set no order.
   
5. If you would like the user to only see values that they submitted, scroll down to Lookup options and select 'Limit options to those created by the current user'.
   
6. If you are you using a Lookup → Dropdown field, enter a value in the Placeholder text setting if you would like placeholder text to appear on the normally blank option.
   
7. Save the form and click Preview. Now the user can select a value from their submitted entries.
   

Set up cascading fields

There are many situations where setting up cascading Lookup fields is useful. One of the most common is a country/state/city scenario. Another common use for this is a vehicle year/make/model scenario. Regardless of the cascading scenario, the directions below can be adapted to apply to your use case.

1. Create a new form. We'll call this the 'Data form' because it will be used to hold all of the year/make/model data, i.e., all of the data that will be retrieved and filtered in the Lookup fields. Add a text field for the Year, a text field for the Make, and a text field for the Model.
2. Import a CSV with all of the year/make/model data into the Data form. If you import a CSV, the CSV headings should match up with the fields in your Data form. If you don't have a CSV to import, you can manually create entries in the Data form.
3. Create a second form. We'll call this the 'End User form' because it will be the form that the end user interacts with.
4. Add a Lookup field for the vehicle year. Set it up to Get options from: Data form → Year field.
   
5. Add a Lookup field for the vehicle make. Set it up to Get options from: Data form → Make field.
   
   Since we want the Make options to change depending on the selected year, set this field up to Watch the 'Year' Lookup field.
   
6. Add a Lookup field for the vehicle model. Set it up to Get options from: Data form → Model field.
   
   Since we want the Model options to change depending on the selected year and make, set this field up to Watch 'Year' Lookup field and the 'Make' Lookup field.
   
7. Save the End User form and click Preview. When you select a Year, the Make options should change. When you select a Make, the Model options will update.
   

Set up multiselect cascading fields

If you want to allow multiple selections for cascading fields, using a Lookup checkbox is useful in this situation. One of the most common scenarios is a hotel/floor/room scenario. The directions below can be adapted to apply to this use case.

1. Create a new form called Data form. This form will be used to hold all of the hotel/floor/room, i.e., all of the data that will be retrieved and filtered in the Lookup checkbox fields. Add a text field for the Hotel, Floor, and Room.
   
2. Import a CSV with all of the hotel/floor/room data into the Data form and make sure that the CSV headings match up with the fields. If you don't have a CSV to import, you can manually create entries in the Data form.
3. Create a second form called End User form. This will be the form that the end-user interacts with.
4. Add a Lookup Checkbox field for the Hotel. Set it up to Get options from: Data form → Hotel field.
   
5. Add a Lookup Checkbox field for the Floor Number. Set it up to Get options from: Data form → Floor Number field. Since we want the Floor Number options to change depending on the selected Hotel, set this field up to Watch the Hotel Lookup field.
   
6. Add a Lookup checkbox field for the Room Number. Set it up to Get options from: Data form → Room Number field. In order for the Room Number options to change depending on the selected Hotel and Floor Number, set this field up to Watch Hotel and the Floor Lookup checkbox field.
   
7. Save the End User form and click Preview. When you multiselect the Hotel, all the Floor Number options will update. When you multiselect the Floor Number, the Room Number options will update.
   

Drill down to a final value

There are many instances where it is useful for a user to select options in one or more fields which then spits out a final value that is retrieved by using the options selected in other fields. Lookup fields can be used for this. To help make the instructions below more clear, we will assume the end goal is to create a form where a user selects a State and their age range which then displays a policy price in a Single Line Text field.

1. Create a new form. We'll call this the 'Data form' because it will be used to hold the insurance policy data. Add a field for the State, Age, and add a Single Line Text field for the Price.
2. Import a CSV with all of the insurance policy data into the Data form. If you import a CSV, the CSV headings should match up with the fields in your Data form. If you don't have a CSV to import, you can manually create entries in the Data form.
3. Create a second form. We'll call this the 'End user form' because it will be the form that the end user interacts with.
4. Add a Lookup field for the State. Set it up to Get options from: Data form → State field.
   
5. Add a Lookup field for the Age. Set it up to Get options from: Data form → Age field.
   
   Since we want the Age options to change depending on the selected State, set this field up to Watch the State Lookup field.
   
6. Add a Single Line Text field type for the price. Select Default Value and click the search icon to get the Lookup default value settings.
   
   Set Search in to Data form → Price field.
   
   Since we want the price to change depending on the selected State and Age, set this field up to Watch the State and Age Lookup field.
   
   Typically you should mark this field as 'Read-only' so users cannot change the value. If you would like to make the value appear as floating text rather than a field input, put the frm_total class in the field's CSS Layout Class box.
7. Save the End User form and click Preview. When you select a State and Age, a price should be displayed in the Single Line Text field.
   

Populate fields with values from a selected entry

If you would like to automatically populate fields based on a selected entry, follow the directions below.

1. Go into edit the form that you want to autofill.
2. Add a Lookup field. Set it up to Get options from: a form/field. It's acceptable to set it up to get options from the current form.
   
3. Open the field options for a field that you want to autofill. (See the list of the types of fields you can autofill.) Select Default Value and click the search icon to get the Lookup default value settings.
   
   Set Search in to the same form that the Lookup field is getting its options from.
   
   In the Watch Lookup Fields option, add the Lookup field from Step 2.
   
4. Repeat the previous step for each field that you want to autofill.
5. Save the form and click Preview. When you select an entry in the Lookup field, the fields that are 'watching' it should automatically populate.
   

Compatible field types

The following field types can be populated automatically by watching a Lookup field:

• Single Line Text
• Email Address
• Website/URL
• Image URL
• Time
• User ID
• Number
• Phone Number
• Date
• Dropdown
• Hidden

This option will be added to additional field types in future releases.

Populate fields by searching entered values

There may be situations where you would like a user to enter a first and last name, for example, and then other form fields automatically populate. Or you may want users to enter an ID number and fields automatically populate with data for that ID number. If you would like to automatically populate fields based on the values entered in one or more fields, follow the directions below.

1. Go into edit the form that you want to autofill.
2. Add a Lookup → Single Line Text field.
   
   Set it up to Search in: the form/field that you would like to search for a first name.
   
3. Add a second Lookup → Single Line Text field. Set it up to Search in: the same form as step 2, but a different field. This will be the field for the user to enter a last name.
   
   Skip this step if a second lookup field is not needed.
4. Add other non-Lookup fields to your form. Open the field options for a field that you want to autofill. Select Default Value and click the search icon to get the Lookup default value settings. Set Search in to the same form that the Lookup fields are searching values from.
   
   In the Watch Lookup Fields option, add the Lookup field from Step 2 and the Lookup field from Step 3.
   
5. Repeat the previous step for each field that you want to autofill.
6. Save the form and click Preview. When you type in a first and last name in the Lookup fields, the other fields that are 'watching' it should automatically populate if a match is found for the entered first and last name.
   

Populate field with ID of an entry

There may be situations where you would like a user to select an entry in the Lookup field, and automatically populate another field with its entry ID. A typical scenario would be to create a form where a user selects a school which then displays the entry ID in a field. The directions below can be adapted to apply to this use case.

1. Create a new form called Data Form. This form will be used to hold the list of school names and their entry ID. Add a text or hidden field for "Entry ID" and another field for "School."
   
2. You could either import a CSV or manually create the options in the "School" field.
3. To save the entry ID of the current entry in the "Entry ID" field, use this code example. Remove any default values and change the visibility to Administrators only if you're using a text field.
4. Create a second form called End User form. It will be the form that the end-user interacts with.
5. Add a Lookup field for "School". Set it up to Get options from: Data form → School field.
   
6. Add a text or hidden field for "Entry ID" which will autofill with the entry ID of the selected School. Open the field options, select Default Value, and click the search icon to get the Lookup default value settings. (See the list of the types of fields you can autofill.)
   Select your Data form in the Search in option. This is the form where the "School" Lookup field options are stored. In the Watch Lookup Fields option, select the "School" Lookup field from step 5.
   
7. Save the form and click Preview. When you select an entry in the "School" Lookup field, the "Entry ID" field that is watching it should automatically populate.
   

Add custom coupon codes

If you want to add a custom coupon code field to your form that automatically deducts the discount amount from the total, you can use Lookup fields to accomplish this.

Copy value to a Lookup field

If you would like to copy a value from a non-Lookup field to a Lookup field, you may use the code below. This is especially useful in cases where the first field cannot be a Lookup (e.g. a field whose value is the result of a Field Calculation instead of a simple selection). The best place to add these code samples is either in your Theme's footer section or the After Fields section of your form Settings → Customize HTML tab.

<script>    
jQuery(document).ready(function($){
    $('#field_nkqtr').change(function(){ 
        var sourceField = $('#field_nkqtr').val();
        $('#field_br4j1').val(sourceField);
        $('#field_br4j1').trigger({ type:'change', originalEvent:'custom' });
    });
});
</script>

Replace nkqtr with the field key of your source field, and br4j1 with the field key of the destination Lookup.

Validate entered value

If you would like to allow users to enter a value which is automatically validated, you could use lookup fields to accomplish this. For this use case, we will validate the value entered in a number field.

1. Create a new form called Number Validation Entry Form. This form will be used to hold the numerical values that will be validated.
2. Add a number field and label it Number Validation. Submit an entry for each value that you want to include in the validation.
3. Go into an existing form, or create a new form, where users can enter a value and trigger the validation.
4. Add a Lookup → Single Line Text field and label it as Number Validation. Set it up to Get Options From the Number Validation Entry Form → Number Validation field.
   
5. Add a Hidden field to the form. Select Default Value and click the search  icon to get the Lookup default value settings. Set it up to Search in the Number Validation Entry Form → Number Validation field.
   
6. Since we want to validate the value depending if it matches the entry in the Number Validation Entry form, set this field up to Watch the Number Validation Lookup field.
7. Go to your form Settings → Styling & Buttons page, and add conditional logic to submit button. Show or enable the submit button if the Hidden field IS NOT EQUAL to blank.
   
8. Add an HTML field with a validation message. You could add some CSS styling, if you want.
   
9. Add conditional logic to the HTML field and set it up to Show this field if ALL of the following match:
   • Hidden field EQUALS to ______(leave blank)
   • Number validation NOT EQUAL to ______(leave blank)

   

Related developer hooks

• Change the comparison operator for Lookup fields with the frm_set_comparison_type_for_lookup hook.
• Add extra content to lookup options with the frm_filtered_lookup_options hook.
• Display User ID field with display name and ID with the frm_filtered_lookup_options hook.
• Remove the current user filter from a Lookup field for a specific user role with the frm_lookup_is_current_user_filter_needed hook.
• Modify the order of options with the frm_order_lookup_options hook.