Skip to content

KrofDrakula/drop

Repository files navigation

@krofdrakula/drop

Bryan Cranston dropping a mic

A small utility to make consuming files dragged into a browser a breeze.

Version Types GZip size

Changelog

TL;DR

import { create } from "@krofdrakula/drop";
create(document.getElementById("drop_target"), {
  onDrop: (files) => console.log(files),
});

Usage

Install the package as a direct dependency:

npm install @krofdrakula/drop

The package provides both CommonJS and ES module versions.

Options

The create function takes the following options:

Parameter Description
onDrop required The function that will be called when files are dropped onto the given element. When a parse function is provided, the files will be transformed from File to whatever the function returns.
onError optional An optional error handler that will capture errors produced when calling the parse function.
parse optional Allows transforming files before handing the results to the onDrop function.
onDragOver optional Fired when dragging files into the HTML element handling the file drop event.
onDragLeave optional Fired when the user drags files off of the HTML element handling the file drop event. It is also triggered just before files are dropped by the user and the onDrop handler fires.
filePicker optional Used to configure the file picker shown when the element is clicked. It is enabled by default but can be disabled by providing { enabled: false }. Other options are passed through to the showOpenFilePicker() function.
onEmptyEnter optional If the file picker is enabled, this handler fires when the pointer enter the hit box of the element without dragging files.
onEmptyLeave  optional If the file picker is enabled, this handler fires when the pointer leaves the hit box of the element without dragging files.

Examples

Styling the element

create options let you hook into events that trigger when files are dragged over or dragged outside of the given element.

For example, you can add or remove a class name when files are over a drop target:

create(myDiv, {
  onDrop: () => {},
  onDragOver: (element) => element.classList.add("over"),
  onDragLeave: (element) => element.classList.remove("over"),
});

To indicate that the element can also be clicked, you can also add handlers that will enable you to signal that affordance:

create(myDiv, {
  onDrop: () => {},
  onEmptyEnter: (element) => element.classList.add("hover"),
  onEmptyLeave: (element) => element.classList.remove("hover"),
});

Note that these are distinct from the default hover event because these handlers will only trigger when the file picker is enabled and the pointer is not dragging any files.

Transforming files

By default, all of the files will be passed through as File objects. If you expect files to be have a particular type of content, you can provide a parse function that will transform the contents into a more convenient form:

import { create, asJSON } from "@krofdrakula/drop";

const myDiv = document.body.querySelector("#drop_target")!;

create(myDiv, {
  onDrop: (files) => console.log(files),
  onError: (err) => console.error(err),
  parse: asJSON,
});

If any file provided triggers a parsing errors, the onDrop handler will not be called and will instead call the onError handler with the error raised.

This package currently provides two helper functions to parse files:

  • asText — transforms each file content into a single string
  • asJSON — parses each file content into its JSON value

You can pass any function that takes a File object and returns any value. Refer to the examples above to see how to integrate with a parsing utility.