@preline/file-upload

File Upload

Tailwind CSS File Upload plugin using Dropzone library to enable drag-and-drop functionality, previews, and progress bars.

Contents

• Overview
• Installation
• Basic usage
• Configuration Options
• JavaScript API
• Events
• Common Patterns
• License

Overview

The File Upload component provides a drag-and-drop file upload interface with preview functionality, progress tracking, and integration with Dropzone.js. It supports multiple file uploads, file type validation, and customizable preview templates.

Key Features:

• Drag-and-drop file upload
• File previews with thumbnails
• Upload progress tracking
• Multiple file support
• File type and extension validation
• Integration with Dropzone.js
• Programmatic control via JavaScript API
• Event system for upload tracking

Installation

To get started, install File Upload plugin via npm, else you can skip this step if you are already using Preline UI as a package.

npm i lodash dropzone @preline/file-upload

CSS

Use @source to register the plugin's JavaScript path for Tailwind CSS scanning, then @import the plugin's CSS files into your Tailwind CSS file.

@import "tailwindcss";

/* @preline/file-upload */
@source "../node_modules/@preline/file-upload/*.js";
@import "./node_modules/@preline/file-upload/variants.css";
@import "./node_modules/@preline/file-upload/theme.css";

JavaScript

Include the JavaScript that powers the interactive elements near the end of your </body> tag:

<script src="./node_modules/lodash/lodash.min.js"></script>
<script src="./node_modules/dropzone/dist/dropzone-min.js"></script>
<script src="./node_modules/@preline/file-upload/index.js"></script>

Manual Initialization

Use the non-auto entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.

<script src="./node_modules/lodash/lodash.min.js"></script>
<script src="./node_modules/dropzone/dist/dropzone-min.js"></script>
<script type="module">
  import HSFileUpload from "@preline/file-upload/non-auto.mjs";

  new HSFileUpload(document.querySelector("#file-upload"));
</script>

Via Bundler

When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module. Dropzone and _ (Lodash) are referenced as globals, so expose them on window before importing the plugin.

@preline/file-upload is the auto-init entry: it scans the DOM and initializes matching elements automatically.

import _ from "lodash";
window._ = _;
import Dropzone from "dropzone";
window.Dropzone = Dropzone;

import "@preline/file-upload";

@preline/file-upload/non-auto is the manual entry: use it when you want explicit control over when initialization happens, either via autoInit() or by creating a specific instance yourself.

import _ from "lodash";
window._ = _;
import Dropzone from "dropzone";
window.Dropzone = Dropzone;

import HSFileUpload from "@preline/file-upload/non-auto";

HSFileUpload.autoInit();

// Or initialize a specific element manually
const el = document.querySelector("#file-upload");
if (el) new HSFileUpload(el);

TypeScript

This package ships with TypeScript type definitions. No additional @types/ package is needed.

Basic usage

The following example demonstrates the minimal HTML structure required for a file upload component. This is a base template without custom styling - you can apply your own CSS classes and styles as needed. The component supports drag-and-drop and file previews.

<div id="hs-file-upload-first" data-hs-file-upload='{
  "url": "/upload"
}'>
  <template data-hs-file-upload-preview>
    <button type="button" data-hs-file-upload-remove>
      Delete!
    </button>
    <span data-hs-file-upload-file-icon>
      <img class="hidden" data-dz-thumbnail />
    </span>
    <div>
      <span data-hs-file-upload-file-name></span>.<span data-hs-file-upload-file-ext></span>
    </div>
    <div data-hs-file-upload-file-size></div>
    <div role="progressbar" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100" data-hs-file-upload-progress-bar>
      <div style="width: 0" data-hs-file-upload-progress-bar-pane></div>
    </div>
    <span data-hs-file-upload-progress-bar-value>0</span>%
  </template>

  <div class="cursor-pointer" data-hs-file-upload-trigger>
    Drop your file here or browse
  </div>

  <div data-hs-file-upload-previews></div>
</div>

Structure Requirements:

• data-hs-file-upload: Required on the container element, contains configuration options
• data-hs-file-upload-preview: Required template element for file previews (should be a <template> element)
• data-hs-file-upload-trigger: Required clickable element for file selection
• data-hs-file-upload-previews: Required container for file preview items
• Various data attributes for preview elements (file name, extension, size, progress, etc.)

Initial State:

• Upload trigger is visible
• Previews container is empty
• Template is hidden (it's a template element)

Configuration Options

Data Options

Note: Please note that this component requires the use of the Dropzone.js plugin. Most options available in the plugin are available in our wrapper.

Data options are specified in the data-hs-file-upload attribute as a JSON object.

Example:

<div data-hs-file-upload='{
  "url": "/api/upload",
  "autoHideTrigger": true,
  "singleton": false
}'>
  <!-- File upload structure -->
</div>

Required CSS Classes / Data Attributes

These data attributes define the structure and must be present for the file upload to function.

Optional CSS Classes / Data Attributes

Tailwind Modifiers

JavaScript API

The HSFileUpload object is available in the global window object after the plugin is loaded.

Instance Methods

These methods are called on a file upload instance.

Static Methods

These methods are called directly on the HSFileUpload class.

Usage Examples

Example 1: Destroying file upload instance

const instance = HSFileUpload.getInstance('#hs-file-upload', true);

if (instance) {
  const { element } = instance;
  const destroyBtn = document.querySelector('#hs-destroy-btn');

  destroyBtn.addEventListener('click', () => {
    element.destroy();
  });
}

Example 2: Accessing Dropzone instance

const instance = HSFileUpload.getInstance('#hs-file-upload', true);

if (instance) {
  const { element } = instance;
  // Access underlying Dropzone instance
  const { dropzone } = element;

  if (dropzone) {
    // Use Dropzone methods
    dropzone.removeAllFiles();
  }
}

Example 3: Destroying file upload instance

const instance = HSFileUpload.getInstance('#hs-file-upload', true);

if (instance) {
  const { element } = instance;
  const removeBtn = document.querySelector('#hs-remove-btn');

  removeBtn.addEventListener('click', () => {
    // Clean up before removing from DOM
    element.destroy();
    // Now safe to remove the element
    document.querySelector('#hs-file-upload').remove();
  });
}

Events

Note: Please note that this component requires the use of the Dropzone.js plugin. Most events available in the plugin are available in our wrapper.

File upload instances emit events through the underlying Dropzone instance. Access the Dropzone instance via element.dropzone to listen to events.

Common Dropzone Events:

• addedfile - When a file is added
• removedfile - When a file is removed
• uploadprogress - During file upload
• success - When file upload succeeds
• error - When file upload fails
• complete - When upload completes (success or error)

Event Usage Example

// Get file upload instance
const instance = HSFileUpload.getInstance('#hs-file-upload', true);

if (instance) {
  const { element } = instance;
  const { dropzone } = element;

  if (dropzone) {
    // Listen to complete event
    dropzone.on('complete', (file) => {
      console.log('File uploaded:', file);
      // Perform actions after file upload completes
      // e.g., update UI, show success message
    });

    // Listen to error event
    dropzone.on('error', (file, errorMessage) => {
      console.log('Upload error:', errorMessage);
      // Handle upload errors
    });

    // Listen to success event
    dropzone.on('success', (file, response) => {
      console.log('Upload successful:', response);
      // Handle successful upload
    });
  }
}

Common Patterns

Pattern 1: Single File Upload

Allow only one file at a time.

<div data-hs-file-upload='{
  "url": "/upload",
  "singleton": true
}'>
  <!-- File upload structure -->
</div>

Pattern 2: Auto-hide Trigger

Hide trigger after files are added.

<div data-hs-file-upload='{
  "url": "/upload",
  "autoHideTrigger": true
}'>
  <!-- File upload structure -->
</div>

License

Copyright (c) 2024 Htmlstream.

Licensed under the MIT License.