Core Documentation

Jump to section

  1. Requirements
  2. Installation
  3. License Registration
  4. Image Hopper Field
  5. Post Image Hopper Field
  6. Notification Attachments
  7. Browser Support
  8. Add-ons Support
  9. Slim Image Cropper
  10. Translations
  11. Developers


  1. PHP 5.6+
  2. WordPress 5.2.0+
  3. Gravity Forms 2.4.0+

The plugin cannot be used without Gravity Forms.


After completing the checkout process you will be redirected to the Purchase Confirmation page. Here you will be able to download your PDF invoice, access the plugin support page, copy your license key, and download the plugin zip file.

Image shows the Purchase Confirmation page, where users can download the plugin zip file.
The Purchase Confirmation page. The area highlighted red is where you can download the plugin zip file.

Once you’ve downloaded the zip, login to your WordPress Admin Area and navigate to Plugins -> Add New. When the page loads, click the Upload Plugin button at the top of the page (right next to the page title) to bring up the file selector. Choose the zip file you just downloaded and click Install Now. If the installation is a success, click the Activate Plugin button to enable Image Hopper on your website.

Image shows the WordPress "Add Plugins" screen with the Upload Plugin functionality selected.
Select the zip and click the Install Now button.
Image shows the screen shows after successfully installing the plugin on WordPress.
After the plugin is successfully installed, click the Activate Plugin button

Note: if your browser auto-extracts zip file, and you’re having trouble uploading the file to your website, you may need to temporarily deactivate this feature and download the plugin again.

License Registration

It’s important to activate your license key on your site(s) so you can receive WordPress one-click updates and support by the Image Hopper team.

To do this, after activating the plugin you can click the Settings link shown next to the Deactivate link on the Image Hopper item shown in the plugins list. You can also reach the settings page by navigating to Forms -> Settings -> Image Hopper.

Copy your license key to the License Key setting and click the Update Settings button to save. If successful you will see a tick icon show up next to the input area. If there is a problem a cross will be shown.

A green tick next to the License Key field means

You can deactivate and remove your license key from the site by deleting it from the License Key setting and saving.

How the user sees the Image Hopper field when filling out a form

Image Hopper Field

The Image Hopper field is available under the Advanced section of the Gravity Forms Editor. The field is very versatile and you can:

  1. Allow multiple images to be uploaded in a single Image Hopper field
  2. Add multiple Image Hopper fields to a single Gravity Form
  3. Automatically downscale images (reducing the image size) to fit within the width/height you set
  4. Set a maximum number of images that can be uploaded per Image Hopper field
  5. Set the maximum file size allowed to be uploaded to the server (calculated using the downscaled image size and not the original file size)
  6. Set the image output quality for JPG/JPEG images
  7. Automatically rotate images based on their EXIF data. This is great for mobile and tablet uploads, where devices are usually rotated when taking photos.
  8. Include Image Hopper fields on any page in your form
  9. Use Image Hopper with the Save and Continue feature
  10. Automatically include uploaded images as attachments in your Notifications
  11. Upload all common image file types, including JPG/JPEG, GIF, and PNG
Start using the image upload feature by including an Image Hopper field in your Gravity Forms form

Field Settings

The Image Hopper field supports many of Gravity Forms common field settings, including:

  • Field Label
  • Description
  • Rule: Required
  • Field Label Visibility
  • Description Placement
  • Custom Validation Message
  • Custom CSS Class
  • Admin Field Label
  • Visibility
  • Conditional Logic

For information about these common field types please refer to Gravity Forms documentation.

Custom Field Settings

The following additional settings are available for the Image Hopper field:

Downscale Images

With modern phones and cameras producing higher quality images, users are more likely to be uploading huge images to your server and this can easily become a storage, bandwidth, and backup nightmare. While the standard File Upload field in Gravity Forms allows you to set a Maximum File Size, it puts the burden on the user to optimize the images prior to upload. With Image Hopper, all you need to do is set a conservative downscale Width/Height and the image(s) will be automatically processed in the user’s browser before uploading. It’s a win-win for everyone involved!

If a user uploads an image that is already below your downscale size it will not be scaled up.

Maximum Number of Files

You can specify the maximum number of images that can be uploaded to an Image Hopper field. You can leave this setting blank for unlimited files, just bear in mind the actual number of files permitted may be limited by your server’s specifications and configuration.

Output Quality

Optimize images even more by setting the output quality of JPG/JPEG images. Set to 0 for the worse possible quality, and 100 for the best. If you don’t set a value, Image Hopper will default to 90.

Maximum File Size

Specify the maximum file size in megabytes allowed for each of the files. When used in conjunction with the Downscale Images setting, the file size is checked after the image has been downscaled.

Viewing Entry

After the form has been submitted, the Image Hopper field will display the number of uploaded images in the Entry List and the actual images on the Entry Details page.

If multiple images are uploaded you’ll see the number of images saved. Single uploads will include a direct link to the file.
Entry Details: the uploaded images are shown on the screen.

Save and Continue

Image Hopper is fully supported when using Gravity Forms Save and Continue feature. Provided the images are successfully uploaded during the initial form submission (and don’t show an error), they will be automatically rehydrated when the recovery link is used.

Note: if the recovery link is used and an image is then deleted without generating a new recovery link, it can put the Image Hopper into an invalid state if the original recovery link is accessed a second time. The image showing an error can either be ignored (the invalid image will be discarded during form submission) or deleted to proceed.

An invalid image state can occur if the Save and Continue feature is used incorrectly.

Export Entries

When the Image Hopper field is included in a CSV export of your entries it will include the full URL to each image, separated by a space/comma/space ( , ). If only a single image is uploaded the separator will not be included.

Merge Tags

Image Hopper has its own individual field tags, but also integrates nicely with Gravity Forms {all_fields} merge tag.

Field Tag


{Field Name:2:modifier}

Without any modifiers, and when in an HTML-output context, all images will be displayed on screen using <img /> tags. If in a text-output context the output is the same as using the :url modifier.


  • :url
    Denotes that the output should show the plain-text secure/masked URL(s) of the uploaded images, separated by a comma (,)
  • :raw
    Denotes that the output should show the plain-text direct URL(s) of the uploaded images, separated by a comma (,)

All Fields Tag

When using the {all_fields} tag (or its variants) in an HTML-output context, all images will be displayed on screen using <img /> tags. If in a text-output context the output is the same as using the :url modifier.

Post Image Hopper Field

Along with the standard Image Hopper field, there is an additional Post Image field powered by Image Hopper, which allows you to easily integrate Image Hopper with Posts and your Media Library. You can find the Post Image field under the Post Fields section of the Gravity Forms Editor.

The Image Hopper Post Image field

The new Post Image field supports most of the same features of the standard Image Hopper field, but, to match Gravity Forms standard Post Image field, only one image can be uploaded per Post Image field.

Custom Field Settings

This field type supports all the same settings as the standard Image Hopper field (minus how many images can be uploaded). This includes Downscaling Images, Output Quality, and the Image Editor functionality (if you’ve that add-on installed). In addition, two new settings are available:

  • Image Metadata – Enable users to enter additional information about the uploaded image, including title, caption, and description.
  • Featured Image – set the image as the post’s Featured Image.
How the Post Image field looks when displayed in the form (theme dependant)

When a form is successfully submitted, a new Post is created with your Post fields and any Image Hopper Post Images will be automatically added to the media library and (optionally) set as the Post’s feature image.

Export Entries

When the Image Hopper Post Image field is added in a CSV export of your entries it will include the full URL to the original image, the title, caption, and description separated by a spaceship operator (|:|).


The Image Hopper Post Image field supports the exact same merge tags as the standard Post Image field:

  • {IH Post Image:2} – Displays the full URL to the image
  • {IH Post Image:2:title} – Displays the image metadata Title
  • {IH Post Image:2:caption}– Displays the image metadata Caption
  • {IH Post Image:2:description}– Displays the image metadata Description

Note: change 2 in the tags above to the correct field ID of the Post Image field.

Notification Attachments

Enable the Notification ‘Attachments’ setting to include Image Hopper as email attachments

You can choose to include the uploaded Image Hopper images as attachments in your Notification emails. To enable, go to your Notification setting and enable the Attach uploaded files to notification option.

Note: this feature does not apply to the Post Image Image Hopper field.

Pay attention to how many Image Hopper fields you have in the form and what the Maximum File Size setting is for each field. Many email providers have a conservative attachment size limit, so it’s best to keep the total size under 10MB. As an example, if you had two Image Hopper fields in your form, you’ll want to set the Maximum File Size to 5MB for each field so you don’t exceed 10MB total.

Browser Support

The Image Hopper field makes use of a progressive enhancement strategy to support a wide range of modern browsers, offering more features to modern browsers who support it. For example, older browsers may not support the dropping of directories, pasting files, or external links. While browsers that do support these features will have them automatically enabled.

The following browsers and devices can successfully use Image Hopper for uploads:


  • Firefox
  • Chrome
  • Safari
  • Edge
  • Internet Explorer 11


  • Safari iOS (version 9 and higher)
  • Chrome Android
  • Firefox Android

Assistive Technology

  • Safari with VoiceOver
  • Chrome with VoiceOver
  • Chrome with NVDA
  • Firefox with NVDA

Add-ons Support

Gravity Forms has a rich first- and third-party add-on ecosystem, and ensuring you can use Image Hopper with all your favourite add-ons is a high priority for us. We’ve support for the following:

Gravity PDF

Gravity PDF is a popular PDF-generation plugin for Gravity Forms. Image Hopper solves all the technical challenges Gravity PDF faces when displaying images in PDFs. The two main issues are:

  1. Images can be automatically downscaled in the browser before upload, which means reasonable image sizes Gravity PDF is working with (keeping the PDFs under 10MB if sending as an attachment, or 20MB otherwise is recommended).
  2. Images are auto-rotated by reading the EXIF data before upload. That means no heavy server-side image rendering and no rotated images in the PDFs.

Since those challenges are resolved, the images uploaded via an Image Hopper field are automatically displayed in the Core (free templates) and Universal PDFs. This is usually without risk of PDF generation issues (but depends on your hosting provider), but if you find there are problems use a smaller downscale width/height and set a smaller Maximum File Size Limit.

Unlike its predecessor, Image Hopper does not wrap the images displayed in the PDFs in an anchor tag, and users won’t be able to click the images to open up the full-sized version in their browser.

Screenshot of Gravity PDF Zadani Template w/ Image Hopper
Image Hopper automatically displaying images in the Core and Universal PDF templates.

Pro Tip: if you limit the Image Hopper field to 1 image you can use the {Field Name:2:raw} merge tag in the Background Image PDF setting (available in the Template section of some PDF templates) to use the uploaded image as a full-page background. Cool, eh!?

Previewer Add-on

The Gravity PDF Previewer add-on allows generated documents to be viewed on screen before the form is submitted. Image Hopper is fully supported, either on the same page as the Previewer or on an earlier page in the form.

An image showing the Gravity PDF Previewer add-on with the Image Hopper field.
Gravity PDF Previewer field in action with Image Hopper

Gravity Flow

Gravity Flow is THE way to build automated business processes into your WordPress website, and Image Hopper natively supports the User Input and Approval Steps (both the WordPress Admin Inbox and the [gravityflow page="inbox"] shortcode methods). The merge tags will also be processed and used anywhere Gravity Flow accepts them, including Notifications and the Outgoing Webhook step.

Gravity Flow Approval Step with Image Hopper field
Gravity Flow User Input Step with Image Hopper field


GravityView is a powerful page builder that uses Gravity Forms data for the source. Image Hopper is fully supported in the Listing / Table Views, and on the Multiple Entries, Single Entry, and Edit Entry View pages.

GravityView's Table view with an Image Hopper field displayed
Image Hopper included in the Multiple Entries Table View
Adding the Image Hopper field to the Edit Entry View
GravityView's Edit Entry view with an Image Hopper field displayed.
Rendering Image Hopper on the Edit Entry View

Editing is supported on both the standard Image Hopper field and the Post Image fields in GravityView. If the Image Hopper Post Image has been set as a Featured Image, GravityView will automatically update the linked Post when updated.

Caution: GravityView has a long-running bug which prevents the correct functionality of upload fields (including Image Hopper) when a validation error occurs on the Edit Entry View. There is currently no workaround.

WooCommerce Gravity Forms Product Add-on

The Woo Gravity Forms add-on (for short) connects WooCommerce and Gravity Forms together to build advanced product configuration forms. The Image Hopper plugins works seamlessly when used in this combination, including when a user might go back and edit the Product/Gravity Form.

An image of the Image Hopper field when used with the WooCommerce Gravity Forms Product add-on.
Image Hopper displayed in a Woo Gravity Forms Product
The Cart after adding a Woo Gravity Forms product with an Image Hopper field.

Gravity Perks Nested Forms

Nested Forms is a powerful Perk created by Gravity Wiz which allows you to build repeater functionality into Gravity Forms (by linking a parent form to a nested child form) and Image Hopper is fully supported when used in the nested form.

Image Hopper displaying in the Nested Form overlay

Note: Nested Forms has two different display modes when filling out child forms. If you find you have a problem with Image Hopper using the default mode, try switch to the alternate by adding this code snippet to your active theme’s functions.php file (or a similar location):

add_filter( 'gpnf_use_jquery_ui', '__return_true' );

Gravity Perk Media Library

Media Library perk enabled for the Image Hopper field

The Media Library perk from Gravity Wiz is supported in standard Image Hopper fields, and you can easily enable this functionality via the Perks tab in the Form Editor. All Image Mergetags listed in the Gravity Wiz documentation is supported.

Note: this feature is not available for the Image Hopper Post Image field

Gravity Forms Advanced Post Creation

The Advanced Post Creation add-on allows you to use any field type in your form to create Posts, Pages, or Custom Post Types with ease. Image Hopper integrates natively with this add-on and allows you to add the standard Image Hopper field images to the Media Library. You can also set a Featured Image if the Maximum Number of File setting is set to 1 for that field.

Adding standard Image Hopper field to the Media Library and as a Featured Image

If you reference the Image Hopper field in the Post Content or Featured Image, those images will automatically be added to the Media Library.

Image Hopper also supports the {apc_media} Mergetag, so you can get the URL or IDs of the images uploaded to the Media Library. You can use the {apc_media} Mergetag in the Content area or Custom Fields. This can be very useful if you want to display a gallery of Image Hopper images in your post:

[gallery ids="{apc_media:2:ids}"]

Note: the Advanced Post Creation plugin doesn’t support Gravity Forms Post fields, which includes the Image Hopper Post Image field type.

Gravity Forms + Custom Post Types

The Image Hopper Post Image field fully supports the use of the Gravity Forms + Custom Post Types plugin, which allows you to change the standard Post type used for the Post fields to a custom post type of your choosing.

Slim Image Cropper

The Slim Image Cropper for Gravity Forms plugin has been discontinued by the original developer and Image Hopper is the recommended replacement. Image Hopper has many of the same features as Slim Image Cropper (and even surpasses it in many areas), but it doesn’t have 100% feature parity (at this stage).

Feature Parity

This is a list of features both Slim Image Cropper and Image Hopper support:

  • Responsive and beautifully animated
  • Correctly handles device orientation
  • Very fast
  • Easy to Configure
  • High Quality User Experience
  • Drag and Drop
  • Resize images automatically
  • User can adjust the crop and rotation (Ultimate + Editor edition only)
  • Define max file upload size
  • Define JPEG compression ratio
  • Define required input image type
  • Customize output image size
  • Supports touch interaction on mobile devices
  • Validate images before upload
  • Multiple fields per form
  • Post Image field type

Not Supported

This is a list of features Slim Image Cropper supports, but Image Hopper doesn’t:

  • Minimum image dimensions
  • Image quality warning (like the minimum image dimensions, but still allows the image to be uploaded)
  • Set image ratio – you can set the image size with the ‘crop’ option enabled to achieve similar results (Ultimate + Editor edition only)
  • Force output format (either JPEG or PNG)

New Features

This is a list of features Image Hopper supports, but Slim Image Cropper doesn’t:

  • Upload multiple images to the same upload field (you are not limited to one image per field)
  • Attach uploaded images to Notification emails
  • Deep integration with the Gravity Forms ecosystem, including native support for popular add-ons like Gravity PDF, GravityView, Gravity Flow, Gravity Perks Nested Forms, Gravity Perks Media Library, Gravity Forms Advanced Post Creation, Gravity Forms + Custom Post Types, and the WooCommerce Gravity Forms add-on.
  • Intuitive Settings – Image Hopper takes a convention over configuration approach to using the plugin, meaning it is easier to setup and configure.

Migrate from Slim Image Cropper

These are the steps you should take after you deactivate Slim Image Cropper and install and activate Image Hopper:

  1. In your admin area, navigate to the Gravity Forms editor for a form that contains a Slim Image Cropper field
  2. Add a new Image Hopper field below each of your Slim Image Cropper fields, and configure accordingly. Because Image Hopper can support multiple images per field, you may be able to consolidate multiple Slim Image Cropper fields.
  3. Leave your existing Slim Image Cropper fields in the form (Image Hopper will automatically hide the Slim and Slim Post fields from your end user, but still display the images in your admin area).
  4. Save your Gravity Form
  5. Test that you can now upload images using Image Hopper and that you don’t see the Slim Image Cropper fields while filling out the form.
  6. Verify you can see the Image Hopper images on the Entry Details page for your newly-submitted test entry
  7. Verify that you can still see the Slim Image Cropper images on the Entry Details page for older entries
  8. Repeat step 1-7 for each of your Gravity Forms


Image Hopper ships with the following translations out of the box:

  • English (en_US)
  • French (fr_FR)
  • Spanish (es_ES)
  • German (de_DE)

If you’d like your language to be supported natively, please get in touch and let us know. The more demand for a specific language the greater the chance of it getting added.


You can use the free Loco Translate plugin to write your own translations specifically for Image Hopper. The Gravity PDF team have an excellent guide which shows you how to go about translating a plugin. Just substitute Gravity PDF for Image Hopper when completing the steps.

If you prefer to generate a PO/MO file for your chosen language using a tool like POEdit, you can find the POT language file at /languages/image-hopper.pot in the plugin zip file.


Below is useful actions/filters that can be used to change how Image Hopper functions:

Javascript Actions/Filters

image_hopper_filepond_config(config, FilePond, $form, currentPage, formId, fieldId, entryId, files, fileInput)

This filter allows you to manipulate the FilePond instance configuration. FilePond is the library used to handle the image uploading functionality, so being able to change how it works based on your needs can be very useful.

config {object} – The FilePond configuration object, which accepts all the properties listed in the FilePond instance documentation.
FilePond {object}The FilePond public API object.
$form {object} – A jQuery object matching the encompassing Gravity Forms <form> element
currentPage {int} – The current page number of the Gravity Forms form.
formId {int} – The Gravity Forms form ID
fieldId {int} – The Image Hopper field ID
entryId {int} – The Gravity Forms entry ID (if one exists)
files {array} – A list of the files already uploaded at the time of initialisation
fileInput {object} – The <input type="file"> object currently being Image Hopper’d


Disable instant upload on image selection/drop:

gform.addFilter('image_hopper_filepond_config', function(config, FilePond, $form, currentPage, formId, fieldId, entryId, files, inputField) {
   config.instantUpload = false
   return config
} )

Insert additional images at the start of the list (instead of after), but limit this behaviour to a specific form and field:

gform.addFilter('image_hopper_filepond_config', function(config, FilePond, $form, currentPage, formId, fieldId, entryId, files, inputField) {
   if(formId == 2 && fieldId == 6) {
      config.itemInsertLocation = "before"
   return config
} )

Automatically add a text watermark to the bottom-left of every uploaded image:

gform.addFilter('image_hopper_filepond_config', function (config, FilePond, $form, currentPage, formId, fieldId, entryId, files, inputField) {
    fileMetadataObject: {

      // The `markup` property is how we define our watermark
      markup: [
            top: '95%',
            left: '3%',
            text: new Date().toLocaleDateString(), // to use the server time, create a hidden GF field with a default value of {date_mdy} and then get its value with `document.getElementById('input_formID_fieldID').value`
            textAlign: 'left',
            fontColor: '#000000',
  return config

Automatically add an image watermark to the bottom-right of every uploaded image:

gform.addFilter('image_hopper_filepond_config', function (config, FilePond, $form, currentPage, formId, fieldId, entryId, files, inputField) {
    fileMetadataObject: {

      // The `markup` property is how we define our watermark
      markup: [
            right: '10px',
            bottom: '10px',
            width: '150px',
            height: '150px',
            src: '', // set full URL to image uploaded to your media library. Use a transparent PNG for transparency
            fit: 'contain'
  return config

Automatically add an image (hosted on the same domain as the form) to Image Hopper on load:

gform.addFilter('image_hopper_filepond_config', function(config, FilePond, $form, currentPage, formId, fieldId, entryId, files, inputField) {
   config.files = [
                source: '', //change this to the URL of your image
                options: {
                        type: 'input'
   return config
} )


While you could create a separate JavaScript file and enqueue it when your desired Gravity Forms form is displayed, it’s far easier to add an HTML field to your form and wrap the filter in <script type="text/javascript"></script> tags.

Easily add the filter to your website via an HTML field

Additional Info

You can manipulate any of the properties listed in the FilePond documentation, but we recommended you steer clear of the following (so you don’t break the core functionality, or use unsupported features):

  • name
  • status
  • element
  • server
  • captureMethod
  • allowReorder