Update v4.2 - New components, 10+ framework guides, and quality improvements. Visit Changelog

........ Github
Figma X (Twitter)

Tailwind CSS File Upload Plugin API

Headless, unstyled file upload plugin built with JavaScript and TypeScript, including installation, usage, options, methods, events, and selectors.

JavaScript Typescript

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.

  1. Install the plugin

    Install @preline/file-upload via npm

    Terminal 
                              
                            npm i lodash dropzone @preline/file-upload

  2. Add the plugin 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.

    main.css 
                              
                            @import "tailwindcss";
                            
                            /* @preline/file-upload */
                            /* [!code highlight:3] */
                            @source "../node_modules/@preline/file-upload/*.js";
                            @import "./node_modules/@preline/file-upload/variants.css";
                            @import "./node_modules/@preline/file-upload/theme.css";

  3. Add the plugin JavaScript

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

    HTML

    Additional Initialization Options

    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.

    HTML (non-auto)

    Via bundler

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

    JavaScript (auto) 
                              
                            import _ from "lodash";
                            window._ = _;
                            import Dropzone from "dropzone";
                            window.Dropzone = Dropzone;

                            import "@preline/file-upload";
    JavaScript (non-auto) 
                              
                            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);

Example

Here is a basic example of a file upload with advanced features.

Basic usage

Prefer to create your own style? Here is a completely unstylized example.

HTML

JavaScript behavior

Data Options

Dropzone.js

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

Check Options
Name Description Options Default value
data-hs-file-upload Activate a File Upload by specifying on an element. Should be added to the container. — —
:extensions A list of extensions and associated icons that will be added inside the container with the data-hs-file-upload-file-icon selector if they match the extension name. object Includes markup. See the code.
:autoHideTrigger If the attribute value is true, then data-hs-file-upload-trigger will disappear if at least one item is added to the upload and will appear if more than one item is not in the upload. boolean false
:singleton If the attribute value is true, then the plugin will remove any previously uploaded file. It needs for emulate simple input file behavior. boolean false

Tailwind Modifiers

Name Description
hs-file-upload-complete:* A modifier that allows you to set Tailwind classes to items that successfully uploaded.

Selectors

Name Description
data-hs-file-upload-trigger Determines which element inside the initialized element will act as a clickable element.
data-hs-file-upload-previews Determines which element inside the initialized element will act as a wrapper for uploaded items.
data-hs-file-upload-clear Determines which element inside the initialized element will act as a button that deletes all files.
data-hs-file-upload-preview Determines which element inside the initialized element will act as a template for the uploading item. Should be a template HTML element.
data-hs-file-upload-file-icon Determines which element inside the uploading item will act as a wrapper for the file icon defined in the extensions property.
data-hs-file-upload-file-name Determines which element inside the uploading item will act as a wrapper for the file name.
data-hs-file-upload-file-ext Determines which element inside the uploading item will act as a wrapper for the file extension.
data-hs-file-upload-file-size Determines which element inside the uploading item will act as a wrapper for the file size.
data-hs-file-upload-remove Determines which element inside the uploading item will act as a remove button.
data-hs-file-upload-reload Determines which element inside the uploading item will act as a re-upload button.
data-hs-file-upload-progress-bar Determines which element inside the uploading item will act as a progressbar.
data-hs-file-upload-progress-bar-pane Determines which element inside the uploading item will act as a progressbar pane, which width will dynamically increase during the uploading process.
data-hs-file-upload-progress-bar-value Determines which element inside the uploading item will act as a current progress value, which will dynamically increase during the uploading process.

Methods

The HSFileUpload object is contained within the global window object

Method Description
Public methods
destroy() Destroys the instance, removes generated markup (if any), removes added classes and attributes.
Static methods
HSFileUpload.getInstance(target, isInstance) Returns the element associated to the target.
  • target should be a Node or string (valid selector)
  • isInstance boolean. Returns the instance instead of Node if true

Destroy instance.

JavaScript 
                      
                        const { element } = HSFileUpload.getInstance('#file-upload', true);
                        const destroyBtn = document.querySelector('#destroy-btn');
                        
                        destroyBtn.addEventListener('click', () => {
                          element.destroy();
                        });

Events

Dropzone.js

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

Check Events

When item successfully uploaded to the server event example.

JavaScript 
                      
                        const { element } = HSFileUpload.getInstance('#hs-file-upload', true);
                        const { dropzone } = element;

                        dropzone.on('complete', () => {
                          console.log('Item uploaded!');
                        });

Ready to use Components

Looking for prebuilt UI components based on the Tailwind CSS? Preline UI packs hundreds of component examples for all your website needs.

File Upload

Explore ready-to-use Tailwind CSS examples built with Preline UI.

View File Upload examples

File Upload

© 2026 Preline Labs.