Repository files navigation

This library provides a reusable dropzone component infrastructure and MaterialDesign implementation.Like the Angular Material repo, it uses a monorepo setup for maximum extensibility.

While the CDK itself is basically headless, the Material implementation relieson theAngular Material components toprovide a consistent style integration.See theDEMO for an example.

You may only want to install the dropzone CDK to apply your own styling.

npm install @ngx-dropzone/cdk

For the Material Design implementation, install both packages.

npm install @ngx-dropzone/cdk @ngx-dropzone/material

For the versioning, we stay consistent with the major Angular releases.So Angular (components) 20 will be compatible with@ngx-dropzone/cdk@20.x.x.

Please note, that v16 is the first officially supported version.For older Angular releases, use the libs at your own risk.

This describes how to use the Material dropzone.If you want to extend the CDK with your own styling, see below.

// in app.component.tsimport{MatFormField,MatLabel}from'@angular/material/form-field';import{MatIcon}from'@angular/material/icon';import{FileInputDirective}from'@ngx-dropzone/cdk';import{MatDropzone}from'@ngx-dropzone/material';@Component({  ...imports:[MatFormField,MatLabel,MatIcon,MatDropzone,FileInputDirective,],  ...})

Now you can use it in your markup.

<mat-form-fieldappearance="fill"><mat-label>Drop anything!</mat-label><ngx-mat-dropzone><inputtype="file"fileInput/></ngx-mat-dropzone><mat-iconmatSuffixcolor="primary">cloud_upload</mat-icon></mat-form-field>

Use thewebkitdirectories attribute to support uploading folders.All files from subdirectories will be provided as a flatFile[], but with an additionalrelativePath property to keep tree structures.

ThefileInput directive on the<input type="file" /> element makes it a valid targetfor[(ngModel)] and[formControl] directives, so you can seamlessly integrate thefile upload into your form.

First, make sure to import theReactiveFormsModule.Then, you're able to define your form control element (incl. validation).

// in app.component.tsimport{ReactiveFormsModule}from'@angular/forms';@Component({selector:"form-control-dropzone",imports:[ReactiveFormsModule,MatError,    ...],template:`    <mat-form-field>      <ngx-mat-dropzone>        <input type="file" fileInput [formControl]="profileImg" />      </ngx-mat-dropzone>      <mat-error>Invalid file type</mat-error>    </mat-form-field>  `,})classDropzoneWithFormControl{validators=[FileInputValidators.accept("image/*")];profileImg=newFormControl<FileInputValue>(null,this.validators);}

In the example above, you may have noticed two new classes, theFileInputValidators andFileInputValue.

TheFileInputValue is just a type alias forFile | File[] | null being the possiblevalues for the form control. Please note that aFile[] is only valid, if themultipleattribute is set on the<input type="file" /> element.

TheFileInputValidators provides custom validator functions for files.

In case you want to give a consistent user feedback about the selectedfiles, we recommend to use theMaterial Chips.

⚠️ Please note that no other file preview will be provided by this lib,because people are way too opinionated about their styling and behaviour.

<mat-form-fieldappearance="fill"><mat-label>Drop anything!</mat-label><ngx-mat-dropzone><inputtype="file"fileInput[formControl]="fileCtrl"/>    @if (fileCtrl.value) {<mat-chip-row(removed)="clear()">      {{ fileCtrl.value.name }}<buttonmatChipRemove><mat-icon>cancel</mat-icon></button></mat-chip-row>    }</ngx-mat-dropzone><mat-iconmatSuffixcolor="primary">cloud_upload</mat-icon></mat-form-field>

exportclassAppComponent{fileCtrl=newFormControl();clear(){this.fileCtrl.setValue(null);}}

Now that we have seen the minimal setup, here are some configuration options for the component markup.

Runnpm run start:[cdk|material] to build and watch for changes on thelibrary packages.

Runnpm run start:app for an example app dev server to test changes locally. Navigate tohttp://localhost:4200/. The app will automatically reload if you change any of the source files.

Other available commands arenpm run [build|test|lint]:[cdk|material].

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 theMaterial dropzone as an example.

The basic setup requires you to extend theDropzoneComponent in your app to apply your own styling and functionality.Use the following skeleton as a starting point. You may always have a look at theMaterial reference implementation linked above.

import{Component}from"@angular/core";import{AcceptService,DropzoneComponent,DropzoneService,FileInputDirective}from"@ngx-dropzone/cdk";@Component({selector:"my-dropzone",imports:[FileInputDirective,DropzoneComponent],providers:[DropzoneService,AcceptService],template:`    <div>      <ng-content select="[fileInput]"></ng-content>    </div>  `,styles:[`      .my-dropzone {        cursor: pointer;        text-align: center;        padding: 40px;        background: platinum;        border: 1px solid black;      }      .dragover > .my-dropzone {        border-width: 2px;      }    `,],})exportclassMyDropzoneextendsDropzoneComponent{}

Please read our Code of Conduct to keep our community open and respectable. 💖

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.

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 viahackingharold@mailbox.org.

This project is MIT-licensed.