droppable

A javascript library to give file dropping super-powers to any HTML element.

Table of Contents

• Motivation
• Features
• Basic usage
• Browser Compatibility
• Installation
• Advanced usage
  • Create a droppable element
  • Listen for dropped files
  • Remove listener for dropped files
  • Get the latest dropped files
  • Trigger prompt for files
  • Enable prompt for files when clicked
  • Disable prompt for files when clicked
  • Enable multiple files drop
  • Disable multiple files drop
  • Enable append CSS class when files are dragged on element
  • Disable append CSS class when files are dragged on element
  • Destroy
• Development
  • Clone the repository

Motivation

Wouldn't it be great if you could drop files in any HTML element allowing you to style the item however you like?

Well now you can! 🎉

Features

• Restrict drop to single or multiple files
• CSS class added when files are being dragged on top of the HTML element (configurable)
• Clicking on the html element also prompts user for files (configurable)
• Zero dependencies
• Tiny! (~4 KB Minified)
• Accessibility support

Basic usage

const Droppable = require('droppable');

const droppable = new Droppable({
    element: document.querySelector('#my-droppable-element')
})

droppable.onFilesDropped((files) => {
    console.log('Files were dropped:', files);
});

// Clean up when you're done!
droppable.destroy();

Browser Compatibility

✔	✔	10+ ✔	✔	✔	✔

Installation

npm install droppable

Advanced usage

Create a droppable element

const Droppable = require('droppable');

const droppable = new Droppable({
    element: document.querySelector('#my-droppable-element')
});

Listen for dropped files

droppable.onFilesDropped((files) => {
    console.log('Files were dropped:', files);
});

Remove listener for dropped files

onFilesDropped returns a function which when called removes the event listener

const eventRemover = droppable.onFilesDropped((files) => {
    console.log('Files were dropped on the element:', files);
});

eventRemover();

Get the latest dropped files

const latestDroppedFiles = droppable.getLatestDroppedFiles();

Trigger prompt for files

Sometimes you will want to prompt the user for files without him dropping files or clicking the element.

droppable.promptForFiles();

Enable prompt for files when clicked

This is by default true

The user will be prompted for files when the droppable element is clicked

// On instantiation
const droppable = new Droppable({
    element,
    isClickable: true
})

// On runtime
droppable.setIsClickable(true);

Disable prompt for files when clicked

The user won't be prompted for files when the droppable element is clicked

// On instantiation
const droppable = new Droppable({
    element,
    isClickable: false
})

// On runtime
droppable.setIsClickable(false);

Enable multiple files drop

This is by default true

The user will be able to drop or select multiple files.

// On instantiation
const droppable = new Droppable({
    element,
    acceptsMultipleFiles: true
})

// On runtime
droppable.setAcceptsMultipleFiles(true);

Disable multiple files drop

The user will be able to drop or select one single file.

// On instantiation
const droppable = new Droppable({
    element,
    acceptsMultipleFiles: false
})

// On runtime
droppable.setAcceptsMultipleFiles(false);

Enable append CSS class when files are dragged on element

This is by default true

The class dragover will be added to the droppable element when files are being dragged on it.

// On instantiation
const droppable = new Droppable({
    element,
    appendStatusClasses: true
})

// On runtime
droppable.setAppendStatusClasses(true);

Disable append CSS class when files are dragged on element

The class dragover won't be added to the droppable element when files are being dragged on it.

// On instantiation
const droppable = new Droppable({
    element,
    appendStatusClasses: false
})

// On runtime
droppable.setAppendStatusClasses(false);

Destroy

The library attaches several events to the HTML element made droppable. The destroy function not only removes all of them but also the onFilesDropped listeners.

droppable.destroy();

Development

Clone the repository

git clone [e-mail]:lifenautjoe/droppable.git

Use npm commands

• npm t: Run test suite
• npm start: Runs npm run build in watch mode
• npm run test:watch: Run test suite in interactive watch mode
• npm run test:prod: Run linting and generate coverage
• npm run build: Generate bundles and typings, create docs
• npm run lint: Lints code
• npm run commit: Commit using conventional commit style (husky will tell you to use it if you haven't :wink:)

Author Joel Hernandez