1 | # file-selector
|
2 |
|
3 | > A small package for converting a [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent) or [file input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file) to a list of File objects.
|
4 |
|
5 | [![npm](https://img.shields.io/npm/v/file-selector.svg?style=flat-square)](https://www.npmjs.com/package/file-selector)
|
6 | [![Tests](https://img.shields.io/github/workflow/status/react-dropzone/file-selector/Test?label=tests&style=flat-square)](https://github.com/react-dropzone/file-selector/actions?query=workflow%3ATest)
|
7 | [![codecov](https://img.shields.io/coveralls/github/react-dropzone/file-selector/master?style=flat-square)](https://coveralls.io/github/react-dropzone/file-selector?branch=master)
|
8 | [![Open Collective Backers](https://img.shields.io/opencollective/backers/react-dropzone.svg?style=flat-square)](#backers)
|
9 | [![Open Collective Sponsors](https://img.shields.io/opencollective/sponsors/react-dropzone.svg?style=flat-square)](#sponsors)
|
10 | [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=flat-square)](https://github.com/react-dropzone/.github/blob/main/CODE_OF_CONDUCT.md)
|
11 |
|
12 | # Table of Contents
|
13 |
|
14 | * [Installation](#installation)
|
15 | * [Usage](#usage)
|
16 | * [Browser Support](#browser-support)
|
17 | * [Contribute](#contribute)
|
18 | * [Credits](#credits)
|
19 | * [Support](#support)
|
20 | * [License](#license)
|
21 |
|
22 |
|
23 | ## Installation
|
24 | You can install this package from [NPM](https://www.npmjs.com):
|
25 | ```bash
|
26 | npm add file-selector
|
27 | ```
|
28 |
|
29 | Or with [Yarn](https://yarnpkg.com/en):
|
30 | ```bash
|
31 | yarn add file-selector
|
32 | ```
|
33 |
|
34 | ### CDN
|
35 | For CDN, you can use [unpkg](https://unpkg.com):
|
36 |
|
37 | [https://unpkg.com/file-selector/dist/bundles/file-selector.umd.min.js](https://unpkg.com/file-selector/dist/bundles/file-selector.umd.min.js)
|
38 |
|
39 | The global namespace for file-selector is `fileSelector`:
|
40 | ```js
|
41 | const {fromEvent} = fileSelector;
|
42 | document.addEventListener('drop', async evt => {
|
43 | const files = await fromEvent(evt);
|
44 | console.log(files);
|
45 | });
|
46 | ```
|
47 |
|
48 |
|
49 | ## Usage
|
50 |
|
51 | ### ES6
|
52 | Convert a [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent) to File objects:
|
53 | ```ts
|
54 | import {fromEvent} from 'file-selector';
|
55 | document.addEventListener('drop', async evt => {
|
56 | const files = await fromEvent(evt);
|
57 | console.log(files);
|
58 | });
|
59 | ```
|
60 |
|
61 | Convert a [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) for an input type file to File objects:
|
62 | ```ts
|
63 | import {fromEvent} from 'file-selector';
|
64 | const input = document.getElementById('myInput');
|
65 | input.addEventListener('change', async evt => {
|
66 | const files = await fromEvent(evt);
|
67 | console.log(files);
|
68 | });
|
69 | ```
|
70 |
|
71 | Convert [FileSystemFileHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle) items to File objects:
|
72 | ```ts
|
73 | import {fromEvent} from 'file-selector';
|
74 |
|
75 | // Open file picker
|
76 | const handles = await window.showOpenFilePicker({multiple: true});
|
77 | // Get the files
|
78 | const files = await fromEvent(handles);
|
79 | console.log(files);
|
80 | ```
|
81 | **NOTE** The above is experimental and subject to change.
|
82 |
|
83 | ### CommonJS
|
84 | Convert a `DragEvent` to File objects:
|
85 | ```ts
|
86 | const {fromEvent} = require('file-selector');
|
87 | document.addEventListener('drop', async evt => {
|
88 | const files = await fromEvent(evt);
|
89 | console.log(files);
|
90 | });
|
91 | ```
|
92 |
|
93 |
|
94 | ## Browser Support
|
95 | Most browser support basic File selection with drag 'n' drop or file input:
|
96 | * [File API](https://developer.mozilla.org/en-US/docs/Web/API/File#Browser_compatibility)
|
97 | * [Drag Event](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent#Browser_compatibility)
|
98 | * [DataTransfer](https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer#Browser_compatibility)
|
99 | * [`<input type="file">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#Browser_compatibility)
|
100 |
|
101 | For folder drop we use the [FileSystem API](https://developer.mozilla.org/en-US/docs/Web/API/FileSystem) which has very limited support:
|
102 | * [DataTransferItem.getAsFile()](https://developer.mozilla.org/en-US/docs/Web/API/DataTransferItem/getAsFile#Browser_compatibility)
|
103 | * [DataTransferItem.webkitGetAsEntry()](https://developer.mozilla.org/en-US/docs/Web/API/DataTransferItem/webkitGetAsEntry#Browser_compatibility)
|
104 | * [FileSystemEntry](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemEntry#Browser_compatibility)
|
105 | * [FileSystemFileEntry.file()](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileEntry/file#Browser_compatibility)
|
106 | * [FileSystemDirectoryEntry.createReader()](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryEntry/createReader#Browser_compatibility)
|
107 | * [FileSystemDirectoryReader.readEntries()](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryReader/readEntries#Browser_compatibility)
|
108 |
|
109 |
|
110 | ## Contribute
|
111 | If you wish to contribute, please use the following guidelines:
|
112 | * Use [Conventional Commits](https://conventionalcommits.org)
|
113 | * Use `[ci skip]` in commit messages to skip a build
|
114 |
|
115 | ## Credits
|
116 | * [html5-file-selector](https://github.com/quarklemotion/html5-file-selector)
|
117 |
|
118 | ## Support
|
119 |
|
120 | ### Backers
|
121 | Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/react-dropzone#backer)]
|
122 |
|
123 | <a href="https://opencollective.com/react-dropzone/backer/0/website" target="_blank"><img src="https://opencollective.com/react-dropzone/backer/0/avatar.svg"></a>
|
124 | <a href="https://opencollective.com/react-dropzone/backer/1/website" target="_blank"><img src="https://opencollective.com/react-dropzone/backer/1/avatar.svg"></a>
|
125 | <a href="https://opencollective.com/react-dropzone/backer/2/website" target="_blank"><img src="https://opencollective.com/react-dropzone/backer/2/avatar.svg"></a>
|
126 | <a href="https://opencollective.com/react-dropzone/backer/3/website" target="_blank"><img src="https://opencollective.com/react-dropzone/backer/3/avatar.svg"></a>
|
127 | <a href="https://opencollective.com/react-dropzone/backer/4/website" target="_blank"><img src="https://opencollective.com/react-dropzone/backer/4/avatar.svg"></a>
|
128 | <a href="https://opencollective.com/react-dropzone/backer/5/website" target="_blank"><img src="https://opencollective.com/react-dropzone/backer/5/avatar.svg"></a>
|
129 | <a href="https://opencollective.com/react-dropzone/backer/6/website" target="_blank"><img src="https://opencollective.com/react-dropzone/backer/6/avatar.svg"></a>
|
130 | <a href="https://opencollective.com/react-dropzone/backer/7/website" target="_blank"><img src="https://opencollective.com/react-dropzone/backer/7/avatar.svg"></a>
|
131 | <a href="https://opencollective.com/react-dropzone/backer/8/website" target="_blank"><img src="https://opencollective.com/react-dropzone/backer/8/avatar.svg"></a>
|
132 | <a href="https://opencollective.com/react-dropzone/backer/9/website" target="_blank"><img src="https://opencollective.com/react-dropzone/backer/9/avatar.svg"></a>
|
133 | <a href="https://opencollective.com/react-dropzone/backer/10/website" target="_blank"><img src="https://opencollective.com/react-dropzone/backer/10/avatar.svg"></a>
|
134 |
|
135 | ### Sponsors
|
136 | Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/react-dropzone#sponsor)]
|
137 |
|
138 | <a href="https://opencollective.com/react-dropzone/sponsor/0/website" target="_blank"><img src="https://opencollective.com/react-dropzone/sponsor/0/avatar.svg"></a>
|
139 | <a href="https://opencollective.com/react-dropzone/sponsor/1/website" target="_blank"><img src="https://opencollective.com/react-dropzone/sponsor/1/avatar.svg"></a>
|
140 | <a href="https://opencollective.com/react-dropzone/sponsor/2/website" target="_blank"><img src="https://opencollective.com/react-dropzone/sponsor/2/avatar.svg"></a>
|
141 | <a href="https://opencollective.com/react-dropzone/sponsor/3/website" target="_blank"><img src="https://opencollective.com/react-dropzone/sponsor/3/avatar.svg"></a>
|
142 | <a href="https://opencollective.com/react-dropzone/sponsor/4/website" target="_blank"><img src="https://opencollective.com/react-dropzone/sponsor/4/avatar.svg"></a>
|
143 | <a href="https://opencollective.com/react-dropzone/sponsor/5/website" target="_blank"><img src="https://opencollective.com/react-dropzone/sponsor/5/avatar.svg"></a>
|
144 | <a href="https://opencollective.com/react-dropzone/sponsor/6/website" target="_blank"><img src="https://opencollective.com/react-dropzone/sponsor/6/avatar.svg"></a>
|
145 | <a href="https://opencollective.com/react-dropzone/sponsor/7/website" target="_blank"><img src="https://opencollective.com/react-dropzone/sponsor/7/avatar.svg"></a>
|
146 | <a href="https://opencollective.com/react-dropzone/sponsor/8/website" target="_blank"><img src="https://opencollective.com/react-dropzone/sponsor/8/avatar.svg"></a>
|
147 | <a href="https://opencollective.com/react-dropzone/sponsor/9/website" target="_blank"><img src="https://opencollective.com/react-dropzone/sponsor/9/avatar.svg"></a>
|
148 | <a href="https://opencollective.com/react-dropzone/sponsor/10/website" target="_blank"><img src="https://opencollective.com/react-dropzone/sponsor/10/avatar.svg"></a>
|
149 |
|
150 | ## License
|
151 | MIT
|