file-selector

What is file-selector?

The file-selector npm package is a utility library for handling file selections in web applications. It provides functions to convert file selections into a standardized format for easier manipulation, including functions to handle selections from both file inputs and drag-and-drop operations.

What are file-selector's main functionalities?

Converting FileList to Array

This feature allows you to convert a FileList object, which is obtained from a file input element, into an array of files for easier iteration and manipulation.

import { fromFileList } from 'file-selector';

const inputElement = document.querySelector('input[type="file"]');
inputElement.addEventListener('change', async (event) => {
  const filesArray = await fromFileList(event.target.files);
  // Now you have an array of files
});

Handling Drag-and-Drop Files

This feature provides a way to handle files dropped into a dropzone on a webpage, converting the DataTransferItem list from the event into an array of files.

import { fromEvent } from 'file-selector';

const dropzone = document.getElementById('dropzone');
dropzone.addEventListener('drop', async (event) => {
  event.preventDefault();
  const items = await fromEvent(event);
  // Now you have an array of files from the drop event
});

Other packages similar to file-selector

dropzone

Dropzone is a widely-used library that provides drag-and-drop file uploads with image previews. It's more feature-rich than file-selector, offering UI for file previews and progress bars, but it's also heavier and more opinionated in terms of functionality.

react-dropzone

React-dropzone is a React wrapper for dropzone.js. It integrates the drag-and-drop file upload functionality into React components, making it convenient for React developers. It is similar to file-selector but tailored specifically for React and provides more UI components.

README

file-selector

A small package for converting a DragEvent or file input to a list of File objects.

Table of Contents

• Installation
• Usage
• Browser Support
• Contribute
• Credits
• Support
• License

Installation

You can install this package from NPM:

npm add file-selector

Bundler

If you are using a bundler such as Vite or Webpack you can import the package directly:

import {fromEvent} from 'file-selector';

Browser

To include the package directly in the browser without a bundling step you can choose to either use a CDN, or include the required files in your own project.

CDN

If you want to use a CDN, you can use Skypack, or any other CDN of your choice. Make sure you are specifying a compatible version range to avoid unexpected breaking changes.

<script type="module">
    import {fromEvent} from 'https://cdn.skypack.dev/file-selector@^1.0.0';
</script>

Self-hosted

Self hosting is also possible, make sure to copy or link the contents of the NPM package into your project and import them as you would any other module.

<script type="module">
    import {fromEvent} from './path/to/file-selector.js';
</script>

Import maps

To avoid repeating the import path and get an experience similar to a bundler you can opt to use an import map.

<script type="importmap">
    {
        "imports": {
            // Using the CDN
            "file-selector": "https://cdn.skypack.dev/file-selector@^1.0.0"
            // Or a path to your own self-hosted version.
            "file-selector": "./path/to/file-selector.js"
        }
    }
</script>
<script type="module">
    import {fromEvent} from 'file-selector';
</script>

Usage

Convert a DragEvent to File objects:

import {fromEvent} from 'file-selector';

document.addEventListener('drop', async (event) => {
    const files = await fromEvent(event);
    console.log(files);
});

Convert a change event for an input type file to File objects:

import {fromEvent} from 'file-selector';

const input = document.getElementById('myInput');
input.addEventListener('change', async (event) => {
    const files = await fromEvent(event);
    console.log(files);
});

Convert FileSystemFileHandle items to File objects:

import {fromEvent} from 'file-selector';

const handles = await window.showOpenFilePicker({multiple: true});
const files = await fromEvent(handles);
console.log(files);

[!NOTE] The above is experimental and subject to change.

CommonJS

Convert a DragEvent to File objects:

const {fromEvent} = require('file-selector');

document.addEventListener('drop', async (event) => {
    const files = await fromEvent(event);
    console.log(files);
});

Browser Support

Most browser support basic File selection with drag 'n' drop or file input:

• File API
• Drag Event
• DataTransfer
• <input type="file">

For folder drop we use the FileSystem API which has very limited support:

• DataTransferItem.getAsFile()
• DataTransferItem.webkitGetAsEntry()
• FileSystemEntry
• FileSystemFileEntry.file()
• FileSystemDirectoryEntry.createReader()
• FileSystemDirectoryReader.readEntries()

Contribute

Checkout the organization CONTRIBUTING.md.

Credits

• html5-file-selector

Support

Backers

Support us with a monthly donation and help us continue our activities. [Become a backer]

Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [Become a sponsor]

License

MIT