file-selector

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

📖 Documentation & live playground →

Table of Contents

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

Installation

You can install this package from NPM:

npm add file-selector

CDN

For CDN usage, load the ESM build directly from a CDN such as esm.sh or jsDelivr:

<script type="module">
  import {fromEvent} from "https://esm.sh/file-selector";

  document.addEventListener("drop", async evt => {
    const files = await fromEvent(evt);
    console.log(files);
  });
</script>

Usage

ES6

Convert a DragEvent to File objects:

import {fromEvent} from "file-selector";
document.addEventListener("drop", async evt => {
  const files = await fromEvent(evt);
  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 evt => {
  const files = await fromEvent(evt);
  console.log(files);
});

Convert FileSystemFileHandle items to File objects:

import {fromEvent} from "file-selector";

// Open file picker
const handles = await window.showOpenFilePicker({multiple: true});
// Get the files
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 evt => {
  const files = await fromEvent(evt);
  console.log(files);
});

MIME types

When the browser doesn't set a File's type, fromEvent infers one from the file extension. By default it uses a small built-in table of the most common types, keeping the bundle lean.

If you need broader coverage, import the full extension-to-MIME table from the file-selector/mime subpath and pass it via the mimeTypes option. Because it's a separate entry point, the full table (~1,200 entries) is only included in your bundle when you import it:

import {fromEvent} from "file-selector";
import {COMMON_MIME_TYPES} from "file-selector/mime";

const files = await fromEvent(evt, {mimeTypes: COMMON_MIME_TYPES});

You can also pass your own Map<extension, mimeType> to restrict or extend the lookup:

const files = await fromEvent(evt, {mimeTypes: new Map([["dwg", "image/vnd.dwg"]])});

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.

Development

Development requires Node.js >= 20. Install the dependencies with:

npm install

The project is built with tsdown (Rolldown), type-checked with TypeScript, tested with Vitest and linted/formatted with oxlint and oxfmt.

| Command | Description | | ------------------------- | -------------------------------------------------------------------------------- | | npm test | Run the test suite in watch mode. | | npm run test:cov | Run the tests once with coverage (runs type-check, lint and format check first). | | npm run type-check | Type-check the sources without emitting. | | npm run lint | Lint the sources (oxlint). | | npm run lint:fix | Apply safe lint fixes. | | npm run lint:type-aware | Type-aware lint via tsgolint (alpha). | | npm run format | Format the sources (oxfmt). | | npm run format:check | Check formatting without writing. | | npm run build | Build the outputs into dist/. | | npm run dev | Build in watch mode. | | npm run docs:dev | Run the Vocs docs site locally. | | npm run docs:build | Build the docs site into site/. | | npm run docs:preview | Preview the built docs site. | | npm run hooks:install | Install the git hooks (prek install). | | npm run hooks:run | Run every git hook over the whole repo. |

The build emits into dist/:

• dist/index.js — ES module
• dist/index.cjs — CommonJS module
• dist/index.d.ts — TypeScript declarations

Git hooks

Git hooks are managed with prek, a fast Rust drop-in for the pre-commit framework (configured in .pre-commit-config.yaml). On commit they format and lint the staged files with oxfmt/oxlint, and check the message against Conventional Commits — the same convention semantic-release uses to cut releases.

prek is a standalone binary, so install it once (e.g. uv tool install prek, brew install prek, or see the install docs). npm install then wires up the hooks automatically; run npm run hooks:install to (re)install them by hand. The hooks are optional — CI enforces the same lint, format and commit checks — but they catch issues before you push.

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