# Angular File Drop
[](https://www.npmjs.com/package/@h-k-dev/angular-file-drop)
[](./LICENSE)
A lightweight, **signal-based** Angular directive for drag-and-drop file and folder uploads — with directory traversal, `accept`-type filtering, and a click-to-open file picker. No stylesheets, no XHR wrappers, no DOM mutation. Just the `File` objects.
## The Philosophy
**[Try the live demo →](https://h-k-dev.github.io/angular-file-drop)**
Dropzone.js is great, but it often fights against modern Angular architecture by injecting its own CSS, mutating the DOM, and hijacking HTTP requests with its own XHR wrappers.
`angular-file-drop` is the "Angular-only" alternative. It does a portion of what Dropzone does, but strictly the Angular way:
- **Native directive** — binds to your existing elements using standard Angular syntax.
- **Headless** — handles the messy HTML5 drag-and-drop events and hands you raw `File` objects.
- **Zero network opinions** — you upload with Angular's own `HttpClient`, keeping interceptors and auth intact.
- **Bring your own UI** — no forced stylesheets. Style your dropzone exactly how your app needs it.
## Features
- Drag-and-drop **and** click-to-open file picker on a single element
- Recursive **folder/directory traversal** (modern File System Access API, with legacy `webkitGetAsEntry` and plain `FileList` fallbacks)
- `accept`-style filtering by extension or MIME (`.png`, `image/*`, `application/pdf`, `*/*`)
- Single- or multiple-file enforcement
- Automatic hidden-file filtering (`.git`, `.DS_Store`, …)
- Signal-based drag-over state for easy template styling
- SSR-safe (guards all browser-only APIs)
- A ready-made `FILE_TYPES` map of common `accept` strings
## Installation
```bash
npm install @h-k-dev/angular-file-drop
```
Requires Angular `17.3+` (standalone directives + signals).
## Quick Start
The directive is standalone — import `AngularFileDrop` directly into your component.
```ts
import { Component } from '@angular/core';
import { AngularFileDrop, FileDropEvent } from '@h-k-dev/angular-file-drop';
@Component({
selector: 'app-uploader',
imports: [AngularFileDrop],
template: `
`,
})
export class Component {
accept = `${FILE_TYPES.ANY_IMAGE},${FILE_TYPES.PDF}`; // "image/*,.pdf,application/pdf"
}
```
You can also write the string by hand: `[acceptedFiles]="'.png,.jpg,image/*'"`.
### Single file only
```html
Drop a single file
```
### Drop a whole folder
`directory` (on by default) recursively walks dropped folders. Each `DroppedFile` carries a `relativePath` that preserves the folder structure.
```ts
template: `
Drop a folder
`;
onDrop(event: FileDropEvent) {
// e.g. "photos/2026/holiday/IMG_001.jpg"
event.files.forEach((f) => console.log(f.relativePath));
}
```
### Open a folder picker on click
Set `directoryPicker` to make the click-to-open dialog a folder chooser instead of a file chooser.
```html
Click to choose a folder
```
### React to drag events and style the zone
The `isDragOver` signal flips while a valid file drag is over the element. Grab the directive instance via the `dropZone` export.
```html
```
### Manual activation (custom button)
Disable the built-in click handling with `isManualActivation` and open the picker yourself from a child control.
```ts
@Component({
imports: [AngularFileDrop],
template: `
Drag files here
`,
})
export class Component {
onDrop(event: FileDropEvent) {
/* ... */
}
}
```
### Disable the zone
```html