Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hackingharold/ngx-dropzone
The missing file input component for Angular Material.
https://github.com/hackingharold/ngx-dropzone
angular cdk drag drop dropzone file material ng ngx upload
Last synced: 3 months ago
JSON representation
The missing file input component for Angular Material.
- Host: GitHub
- URL: https://github.com/hackingharold/ngx-dropzone
- Owner: hackingharold
- License: mit
- Created: 2023-03-16T22:16:24.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-01T12:22:23.000Z (4 months ago)
- Last Synced: 2024-11-08T13:24:51.445Z (3 months ago)
- Topics: angular, cdk, drag, drop, dropzone, file, material, ng, ngx, upload
- Language: TypeScript
- Homepage:
- Size: 2.17 MB
- Stars: 34
- Watchers: 1
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: readme.md
- Contributing: .github/CONTRIBUTING
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT
- Security: .github/SECURITY
Awesome Lists containing this project
- awesome-angular - ngx-dropzone - The missing file input component for Angular Material. (Table of contents / Third Party Components)
- fucking-awesome-angular - ngx-dropzone - The missing file input component for Angular Material. (Table of contents / Third Party Components)
- fucking-awesome-angular - ngx-dropzone - The missing file input component for Angular Material. (Table of contents / Third Party Components)
README
# ngx-dropzone
[](https://stackblitz.com/edit/ngx-dropzone-showcase?file=src%2Fmain.ts)
[](https://github.com/hackingharold/ngx-dropzone/blob/HEAD/LICENSE)
[](https://www.npmjs.org/package/@ngx-dropzone/cdk)
[](https://www.npmjs.org/package/@ngx-dropzone/material)
This library provides a reusable dropzone component infrastructure and Material
Design implementation.
Like the Angular Material repo, it uses a monorepo setup for maximum extensibility.
| Package | Description |
| ------------------------ | ------------------------------------------------ |
| `@ngx-dropzone/cdk` | Common dropzone interaction patterns. |
| `@ngx-dropzone/material` | Material Design implementation based on the CDK. |
While the CDK itself is basically headless, the Material implementation relies
on the [Angular Material components](https://github.com/angular/components) to
provide a consistent style integration.
See the [DEMO](https://stackblitz.com/edit/ngx-dropzone-showcase?file=src%2Fmain.ts) for an example.
## Installation
You may only want to install the dropzone CDK to apply your own styling.
```sh
npm install @ngx-dropzone/cdk
```
For the Material Design implementation, install both packages.
```sh
npm install @ngx-dropzone/cdk @ngx-dropzone/material
```
## Versioning
For the versioning, we stay consistent with the major Angular releases.
So Angular (components) 18 will be compatible with `@ngx-dropzone/[email protected]`.
Please note, that v16 is the first officially supported version.
For older Angular releases, use the libs at your own risk.
## Basic usage
This describes how to use the Material dropzone.
If you want to extend the CDK with your own styling, see below.
```js
// in app.module.ts
import { MatFormFieldModule } from '@angular/material/form-field';
import { DropzoneCdkModule } from '@ngx-dropzone/cdk';
import { DropzoneMaterialModule } from '@ngx-dropzone/material';
@NgModule({
...
imports: [
MatFormFieldModule,
DropzoneCdkModule,
DropzoneMaterialModule,
],
...
})
export class AppModule { }
```
Now you can use it in your markup.
```html
Drop anything!
cloud_upload
```
Use the `webkitdirectories` attribute to support uploading folders.
All files from subdirectories will be provided as a flat `File[]`, but with an additional `relativePath` property to keep tree structures.
## Usage with FormControl and validation
The `fileInput` directive on the `` element makes it a valid target
for `[(ngModel)]` and `[formControl]` directives, so you can seamlessly integrate the
file upload into your form.
First, make sure to import the `ReactiveFormsModule`.
```js
// in app.module.ts
import { ReactiveFormsModule } from '@angular/forms';
@NgModule({
...
imports: [
ReactiveFormsModule,
...
],
...
})
export class AppModule { }
```
Then, you're able to define your form control element (incl. validation).
```ts
@Component({
selector: "form-control-dropzone",
template: `
Invalid file type
`,
})
class DropzoneWithFormControl {
validators = [FileInputValidators.accept("image/*")];
profileImg = new FormControl(null, this.validators);
}
```
In the example above, you may have noticed two new classes, the `FileInputValidators` and `FileInputValue`.
The `FileInputValue` is just a type alias for `File | File[] | null` being the possible
values for the form control. Please note that a `File[]` is only valid, if the `multiple`
attribute is set on the `` element.
The `FileInputValidators` provides custom validator functions for files.
| Validator | Description |
| ----------------------------- | --------------------------------------------- |
| `FileInputValidators.accept` | Defines accepted file types. |
| `FileInputValidators.minSize` | Sets the required minimum file size in bytes. |
| `FileInputValidators.maxSize` | Sets the maximum allowed file size in bytes. |
## File Previews
In case you want to give a consistent user feedback about the selected
files, we recommend to use the [Material Chips](https://material.angular.io/components/chips/overview).
⚠️ Please note that no other file preview will be provided by this lib,
because people are way too opinionated about their styling and behaviour.
```html
Drop anything!
@if (fileCtrl.value) {
{{ fileCtrl.value.name }}
cancel
}
cloud_upload
```
```js
export class AppComponent {
fileCtrl = new FormControl();
clear() {
this.fileCtrl.setValue(null);
}
}
```
## Configuration
Now that we have seen the minimal setup, here are some configuration options for the component markup.
### FileInput directive
| Property | Description | Options |
| ---------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `accept` | Defines the accepted file types. | See [here](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept) |
| `mode` | On select, either replace (default) or append the new files. Works only with multiple attribute. | `replace` or `append` |
| `multiple` | Allow multiple files to be selected. | `Boolean` |
| `disabled` | Disables any interaction. | `Boolean` |
### Material dropzone
| Property | Description |
| ------------- | ---------------------------------------------------------------- |
| `required` | Sets the native required property. |
| `placeholder` | The placeholder text has no effect, use `` instead. |
## Development server
Make sure you have [Bun](https://bun.sh/) installed as a drop-in replacement for npm.
Run `bun run start:[cdk|material]` to build and watch for changes on the
library packages.
Run `bun run start:app` for an example app dev server to test changes locally. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
Other available commands are `bun run [build|test|lint]:[cdk|material]`.
## Extensibility
This library provides a ready-to-use Material Design implementation for the dropzone.
However, you might want to apply your own custom styling (or library).
In this case, you're able to build upon the dropzone CDK. See the [Material dropzone](/projects/material/src/lib/mat-dropzone/mat-dropzone.component.ts) as an example.
The basic setup requires you to import the `DropzoneCdkModule` into your app.
```js
// in app.module.ts
import { DropzoneCdkModule } from '@ngx-dropzone/cdk';
@NgModule({
...
imports: [
DropzoneCdkModule,
],
...
})
export class AppModule { }
```
Next up, you extend the `DropzoneComponent` and apply your own styling and functionality.
Use the following skeleton as a starting point. You may always have a look at the
Material reference implementation linked above.
```ts
import { Component } from "@angular/core";
import { DropzoneComponent } from "@ngx-dropzone/cdk";
@Component({
selector: "my-dropzone",
template: `
`,
styles: [
`
.my-dropzone {
cursor: pointer;
text-align: center;
padding: 40px;
background: platinum;
border: 1px solid black;
}
.dragover > .my-dropzone {
border-width: 2px;
}
`,
],
})
export class MyDropzone extends DropzoneComponent {}
```
## Contributing
### Code of Conduct
Please read our `Code of Conduct` to keep our community open and respectable. 💖
### Want to Help?
Want to report a bug, contribute some code, or improve the documentation? Excellent! Read up on our guidelines for contributing and then check out one of our issues labeled as `help wanted` or `good first issue`.
### Security
If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and not open a public issue. Security issues in this open source project can be safely reported via `[email protected]`.
### License
This project is MIT-licensed.