Skip to content

Commit

Permalink
improve Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
alexfriesen committed Mar 4, 2024
1 parent 5427ec0 commit 45d44b7
Showing 1 changed file with 92 additions and 9 deletions.
101 changes: 92 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,102 @@
# data-transfer-helper

[![npm][badge-npm-version]][url-npm]
[![MIT licensed][badge-licence]][url-licence]
[![Size][badge-bundle]][url-bundle]

Helper Function for handling DnD DataTransfer Events.

Fetures:
Fetures:

- parse dropped directories via File System Access API or webkitGetAsEntry
- uses generator functions
- types provided
- blazing fast generator functions
- small bundle size
- no dependencies
- filter files
- typescript support

## Getting started:

install the package:

```bash
npm install data-transfer-helper
```

And use it in your code:

```typescript
import { parseFilesFromEvent } from "data-transfer-helper";

document.addEventListener("drop", async function (event: DragEvent) {
event.preventDefault();
event.stopPropagation();

const files = await parseFilesFromEvent(event);
});
```

## Options:

### filters:

You can provide a filter function to filter the files that are returned.

## Example:
```typescript
import { parseFilesFromEvent } from 'data-transfer-helper';
import { parseFilesFromEvent, dotFileFilter } from "data-transfer-helper";

document.addEventListener('drop', async function(event: DragEvent) {
event.preventDefault();
event.stopPropagation();
document.addEventListener("drop", async function (event: DragEvent) {
event.preventDefault();
event.stopPropagation();

const files = await parseFilesFromEvent(event);
const files = await parseFilesFromEvent(event, {
filters: [dotFileFilter, (file: File) => file.size < 1000000],
});
// files will only contain files that are not dot files and are smaller than 1MB
});
```

### addDirectoryName:

You can provide a flag to add directory paths to filenames.

```typescript
import { parseFilesFromEvent } from "data-transfer-helper";

document.addEventListener("drop", async function (event: DragEvent) {
event.preventDefault();
event.stopPropagation();

const files = await parseFilesFromEvent(event, {
addDirectoryName: true,
});
// files will contain the full path to the file
// e.g. Downloads/file.txt
});
```

### disableFileSystemAccessAPI

You can provide a flag to disable the experimetal File System Access API.

```typescript
import { parseFilesFromEvent } from "data-transfer-helper";

document.addEventListener("drop", async function (event: DragEvent) {
event.preventDefault();
event.stopPropagation();

const files = await parseFilesFromEvent(event, {
disableFileSystemAccessAPI: true,
});
// files will fallback to webkitGetAsEntry and getFile()
});
```

[url-npm]: https://www.npmjs.com/package/data-transfer-helper
[url-bundle]: https://img.shields.io/bundlephobia/minzip/data-transfer-helper
[badge-bundle]: https://img.shields.io/bundlephobia/minzip/data-transfer-helper
[url-licence]: https://github.com/data-transfer-helper/blob/master/LICENSE
[badge-licence]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square
[badge-npm-version]: https://img.shields.io/npm/v/data-transfer-helper.svg?style=flat-square
[badge-npm-downloads]: https://img.shields.io/npm/dm/data-transfer-helper.svg?style=flat-square

0 comments on commit 45d44b7

Please sign in to comment.