ngx-uploadcare-widget

Angular 2+ wrapper for Uploadcare Widget.

Uploadcare Widget is an HTML5 file uploader, a part of the Uploadcare ecosystem.

• Install
• Usage
• Configuration
• Localization
• Security issues
• Feedback

Install

For Angular v14+ — install ngx-uploadcare-widget v4.x

npm install [email protected] uploadcare-widget

For Angular v12+ — install ngx-uploadcare-widget v3.x

npm install [email protected] uploadcare-widget

For Angular from v9 to v11 — install ngx-uploadcare-widget v2.x

npm install [email protected] uploadcare-widget

For Angular v8 and lower — install ngx-uploadcare-widget v1.x

npm install [email protected] uploadcare-widget

Usage

The basic wrapper usage scenario can be described in four steps.

Step 1. Import the module

import { UcWidgetModule } from 'ngx-uploadcare-widget';

Step 2. Import the module to yours

@NgModule({
  imports: [
    ...,
    UcWidgetModule,
  ],
  ...
})
...

Step 3. Use the component in your template

<!-- with default markup -->
<ngx-uploadcare-widget
  images-only="true"
  public-key="YOUR_PUBLIC_KEY">
</ngx-uploadcare-widget>

<!-- without any markup -->
<ngx-uploadcare-widget-custom
  images-only="true"
  public-key="YOUR_PUBLIC_KEY">
</ngx-uploadcare-widget-custom>

Step 4. Have fun with the widget events

The component currently supports three widget events:

• on-change
• on-upload-complete
• on-progress

Here is how you can handle those three,

<ngx-uploadcare-widget
  images-only="true"
  public-key="demopublickey"
  (on-upload-complete)="yourOnUploadHandler($event)"
  (on-change)="yourOnChangeHandler($event)"
  (on-progress)="yourOnProgressHandler($event)">
</ngx-uploadcare-widget>

You can learn more about this widget events in our docs.

Configuration

Supported input attributes

All the following attributes correspond to the ones listed in the widget docs, but without the data- prefix.

• public-key
• multiple
• multiple-max
• multiple-min
• images-only
• preview-step
• crop
• image-shrink
• clearable
• tabs
• input-accept-types
• preferred-types
• system-dialog
• secure-signature
• secure-expire
• value
• cdn-base
• do-not-store
• validators

Events

• on-upload-complete
• on-change
• on-progress - fired several times while upload with progress data.

Events usage example:

  onUpload(info) {
    console.log('fired Event "onUpload"');
    console.log(info);
  }

  onProgress(progress) {
    console.log('fired Event "onProgress with data:"');
    console.log(progress);
  }

  onChange(file) {
    if(!file) {
      return;
    }
    console.log('fired Event "onChange"');
  // input file parameter depends on "multiple-files" widget attribute
    if(this.multipleFiles) {
  //  file contains 2 methods:
  //  .promise() - returns the general promise for all uploaded files which resolves into an uploaded file group info
  //  .files() - returns an array of promises: one per each uploaded file. Each promise resolves into an uploaded file info
      console.log(file);
      if(file.promise) {
        file.promise().then((groupInfo) => {
          console.log('resolved general promise from "onChange" with data:');
          console.log(groupInfo);
        });
      }
      if(file.files) {
        file.files().forEach((promise) => {
          promise.then((fileInfo) => {
            console.log('resolves file promise with file info:');
            console.log(fileInfo);
          });
        });
      } else {
  // file contains uploaded file info
        console.log(file);
      }
    }
  }

Methods

The components provides following public methods:

• clearUploads() - Removes all current uploads from the widget. You can use the method to reset a form even if a user has already uploaded some files.
• reset(clearUploads = false) - Resets the widget, You can also remove all the current uploads if clearUploads is set to true
• openDialog() - Opens Uploadcare widget dialog with current configuration.
• reject() - Closes the dialog opened with openDialog() method only and discards any file selection.

All methods are accessible from a parent component via the @ViewChild() approach.

Localization

It is possible that your locale is not available in the widget yet. If that’s the case, contributing your locale might be a good idea. This can be done by forking the main repository and adding a localization file here.

The quick way of implementing your locale would be overriding any of the existing ones via the UPLOADCARE_LOCALE_TRANSLATIONS property.

Security issues

If you think you ran into something in Uploadcare libraries which might have security implications, please hit us up at [email protected] or Hackerone.

We'll contact you personally in a short time to fix an issue through co-op and prior to any public disclosure.

Feedback

Issues and PRs are welcome. You can provide your feedback or drop us a support request at [email protected].