Adding file uploads to Gravity Forms

This tutorial is about building Gravity Forms capable of receiving user-generated files by integrating with Uploadcare. If you’re running a WordPress powered website, you might also want to check out our WP integration tutorial.

In fact, integrating with Uploadcare provides you with more features than just file uploads. You’re also getting Uploadcare storage and CDN. The former ensures you don’t have to set up a separate storage for user-generated content while the latter makes sure uploaded files can be delivered across 5 continents in an effecient manner. Fast and secure delivery is especially useful if your case is about making uploaded content publicly available.

Gravity Forms can be highly customized, and one of the ways to do that would be “filters”. WordPress defines filters as special functions allowing plugins to modify various types of internal data. Sounds good, let’s build a form for submitting travel expenses.

What we need first

  1. Uploadcare account. Free plan will do.
  2. Gravity Forms account, basic license.

Once you create an Uploadcare account, check out your dashboard. There you can either create a new project or discover keys for an existing one. You will need your project’s public key when setting up Uploadcare Widget: the key identifies an account/project user uploads will go to.

Step 1: Include Uploadcare library

Locate the file named header.php under a root directory of your WordPress theme. Place the following line in the <head> section:

<script src="" charset="utf-8"></script>

Step 2: Add a field button to your admin interface

The code below does the thing. Place it in the file called functions.php. The file is usually located under your WordPress theme directory, e.g. /var/www/wordpress/wp-content/themes/twentyfifteen/functions.php.

add_filter('gform_add_field_buttons', 'ih_gform_add_field_buttons');
function ih_gform_add_field_buttons($field_groups) {
  foreach ($field_groups as &$group) {
    if ($group['name'] == 'advanced_fields') {
      $group['fields'][] = array(
        'class' => 'button',
        'value' => __('Uploadcare', 'gravityforms'),
        'data-type' => 'uploadcare'
  return $field_groups;

Step 3: Add form settings to the Uploadcare field

The code in this step injects settings attributes into widget fields: yes, there can be many. This allows to control widget labels, descriptions, layouts, and validation settings via the Gravity Forms admin interface.

add_action('gform_editor_js', 'editor_script', 10, 5);
function editor_script(){
  fieldSettings['uploadcare'] = '.label_setting, .description_setting, .admin_label_setting, .size_setting, .default_value_textarea_setting, .error_message_setting, .css_class_setting, .visibility_setting'
add_filter('gform_admin_pre_render', 'ih_gform_admin_pre_render');
function ih_gform_admin_pre_render($form) {
  foreach ($form['fields'] as $i => $field) {
    if ($field['type'] == 'uploadcare') {
      $form['fields'][$i]['displayAllCategories'] = true;
      $form['fields'][$i]['adminLabel'] = 'Receipts';
      $form['fields'][$i]['adminOnly'] = false;
  return $form;

As you can see, we’ve just changed our field lable to “Receipts”. We’ve done that to hint our users at the type of content to upload.


Step 4: Adding the widget to your form

That’s where we get practical and use the code that actually adds the uploading widget to the form we’ve been building. For our custom receipt field, we’ll be using gform_field_input. And here’s how:

add_action('gform_field_input', 'ih_gform_field_input', 10, 5);
function ih_gform_field_input($input, $field, $value, $lead_id, $form_id) {
  if ($field['type'] == 'uploadcare') {
    $input = sprintf(
      '<p><input type="hidden" name="input_%s" role="uploadcare-uploader" id="%s" class="gform_uploadcare" data-multiple="true" data-images-only="true" value="" /></p>',
  return $input;

Please note, $input can be modified to add any number of widget options. The code above does not contain any Uploadcare project key. In order for any uploaded content to go to the specified project, please include the data-public-key option followed by your project’s public key. See Step 1 to revise what the key is and how to get it. Note, if you’re uploading non-image content, make sure to add billing info to your account.

In the example above, we use data-images-only to allow image file uploads only and data-multiple to let users send many files in one go.

Next, locate your Gravity Toolbox, switch to “Advanced Fields” and click “Uploadcare” as shown in the picture.


Now you should be able to see the Uploadcare button in your Gravity Forms toolbox.

Admin page:


Public page:


We did not show how to add simple text and date fields to the form: those are intuitive.

Step 5: Uploadcare Widget custom styles (Optional)

It’s pretty often that you’d want to change the widget’s button text and styling. That’s how you do it in Gravity Forms.

Say, you want a black button.

Create a file called uploadcare-style.css and put the following code in there:

.uploader-dark-button .uploadcare-widget-button-open {
    background-color: #333333;
    border-radius: 0;
.uploader-dark-button .uploadcare-widget-button-open:hover {
    background-color: #333333;

Put the file in your base directory, e.g. wp-content/plugins/gravityforms/css/uploadcare-style.css.

Now, we need to inject the stylesheet into our page. Gravity Forms renders custom scripts through gform_enqueue_scripts. So, our next step is adding the code below to functions.php (you may want to refer to steps 2-4 to recall the details.) Here is the code:

add_action('gform_enqueue_scripts', 'enqueue_custom_script');
function enqueue_custom_script() {
  wp_enqueue_style('gforms_uploadcare_css', GFCommon::get_base_url().'/css/uploadcare-style.css');

Finally, click the Uploadcare field, then click the “Appearance” tab and locate the field named “Custom CSS class.” Enter uploader-dark-button and click “Update.”



Gravity Forms is able to automatically pick up and apply styles to your widget. For more ideas on styles please check out our widget docs and knowledge base.


We have just embedded Uploadcare Widget in Gravity Forms. From now on, it will just work.

If you've come up with any questions beyond this tutorial or our docs, shoot a note over If you liked the article, subscribe to our newsletter: some great stuff happens there.

We’re always happy to help with code, integration, and other stuff. Search our site for more info or post your question in our Community Area.