Skip to main content

File Upload Drag & DropProImproved in 5.17+

An advanced premium javascript-based file uploading field, using Craft Assets. The field.type property value is file-dnd (for conditionals).

​Settings

  • Can control the placeholder wording, e.g. Drag and drop files here, or click to upload.
  • Can control the wording of the confirmation to remove a file, e.g. Are you sure you want to remove this file?.New in 5.11.8+
  • Choose a default style/theme, e.g. Light or Dark.
  • Choose an accent color (this affects the default color for the field border and delete button).
  • Must have a Craft Asset Source location where the file will be uploaded to.
    • Does NOT work with Image Transforms.
    • Upload Location Subfolder (optional) - the subfolder path that files should be uploaded to. May contain form.handle or form.id variables or something like currentUser.id for folders based on user ID's or "now"|date("Y/m") to dynamically generate folders based on dates as well.
  • Specify the number of files allowed to upload.
  • Define maximum file size per file (in KB). Default is 2048 KB (2MB). Is subject to:
  • Select which file types can be uploaded.
    • Leaving all options unchecked will allow ALL file types.
  • Can use your own custom dialog element.New in 5.11.8+
  • Show Upload RequirementsNew in 5.17+
    • Displays the allowed file kinds, maximum number of files, and maximum size per file beneath the upload field. The text is generated automatically from the field's settings.

​Behavior & Limitations

  • Unlike the regular File Upload field, the File Upload Drag & Drop field will remember files that have been uploaded to it regardless of the context: errors upon submission, multi-page forms, returning to edit the submission later.
    • If the form is never completed, incomplete submissions are stored for 3hrs, and then are removed (along with the files) after that.
  • While files are uploading, Freeform will disable the Submit button so that the form has time to finish uploading the files. If the form is submitted while files are still uploading, any that are incomplete will not be saved.
  • If you're handling sensitive files, you may wish to choose an Asset volume without public URL's (Assets in this volume have public URLs toggle is off). However, please note that image file thumbnails will only be present directly after initial upload. Afterward (error when submitting, multi-page forms, returning to edit) the image thumbnails will no longer be accessible to Freeform.

​Styling & Customization

The form builder includes some options for controlling basic styling, but you can also customize the appearance of the Drag and Drop File Upload field by using your own CSS. To avoid name collision and have maximum flexibility, the CSS class names use BEM methodology. You will also likely need to specify !important for each override to ensure it takes effect.

Below is a list of all class names listed in SCSS: Renamed in 5.0+

.freeform-file-dnd__input {
  &__placeholder {
  }
  &__messages {
  }
  &__preview-zone {
    &__file-preview {
      &__filename {
      }
      &__filesize {
      }
      &__thumbnail {
        &__extension-label {
        }
        &__remove-button {
        }
        &__errors {
        }
        &__progress {
        }
      }
    }
  }
}

​Customize Upload RequirementsNew in 5.17+

​Appearance

Style the generated text using .freeform-upload-requirements:

.freeform-upload-requirements {
  color: #6b7280;
  font-size: 0.8125rem !important;
  margin-top: 0.5rem !important;
}

The text also inherits the field's instruction classes. Some default spacing and typography are applied inline, so overrides may require !important.

​Placement in Custom Templates

Requirements normally appear automatically after the upload control. To position them separately, suppress that output and render it where needed:

{{ field.renderInput({ uploadRequirementsInInput: false }) }}

{# Other field markup… #}

{{ field.renderUploadRequirements }}
{% do field.setParameters({ uploadRequirementsInInput: true }) %}

Keep Show Upload Requirements enabled. The generated markup preserves the description linked to the upload control for accessibility.

​Wording and Custom Markup

The file-kind labels and requirement messages are translatable. To use your own markup while retaining the automatically generated text:

{% if field.showUploadRequirements %}
  <p
    id="{{ field.idAttribute }}-upload-requirements"
    class="my-upload-requirements"
  >
    {{ field.uploadRequirementsText }}
  </p>
{% endif %}

Use this instead of field.renderUploadRequirements and suppress the automatic output as shown above. Preserve the element's ID so the upload control's accessible description remains connected.

​Templating

PropertyDescription
field.fileKindsAn array of allowed file kinds, such as image, document, or audio.
field.maxFileSizeKBThe maximum permitted size of each file, in kilobytes.
field.fileCountThe maximum number of files allowed. A value greater than 1 permits multiple files.
field.showUploadRequirementsNew in 5.17+Whether Show Upload Requirements is enabled.
field.uploadRequirementsTextNew in 5.17+The translated requirements text, including allowed file kinds, maximum file count, and maximum size per file. Returns an empty string when requirements are disabled.

The field.renderUploadRequirements() method renders the requirements as an HTML block. See Styling & Customization for custom placement and markup examples.

By default, field.render() and field.renderInput() include this block automatically when Show Upload Requirements is enabled.

​Resources

Page Feedback