Welcome to @sharr/dom-upload 👋

The sharr.io library for direct uploads from the browser.

Provides two types of JS API:

• generic JS class
• React HOC

Install

npm install @sharr/dom-upload

Usage

Prerequisites

Register your account on https://sharr.io - the Upload as a Service platform and obtain the clientToken for your website.

Options

Regardless of the way you use this package, the underlying API is the same, so the options configuration is generally the same.

| option | required | description | |----------------------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | clientToken | yes | clientToken obtained when registering your website/app on https://sharr.io | | inputElement | optional | Reference to DOM <input type="file"> element,use when you want to allow selecting file from computer or mobile One of inputElement, dropContainerElement, handlePaste options is required for automation of the upload proces. If none of those options is set, you'll need to manually call setFile(file) method to provide file for upload. | | dropContainerElement | optional | Reference to DOM container, which allows for providing file for upload using drag & drop method | | handlePaste | optionaldefault: false | Set true to enable pasting an image from clipboard.Only one instance of SharrDomUpload with handlePaste set to true can be created on single web page. | | autoSubmit | optionaldefault: false | Set true to enable auto-submitting the file after selecting | | autoEnable | optionaldefault: true | Set false if you don't want created instance to be instantly active. When set to false, you need to later call enable() method to activate the instance. | | onSelect | optional | A callback to be called when file gets selected. Called with two arguments: (1) a native File object, (2) a native Event object being a source of selecting the file | | onSubmit | optional | A callback to be called when submit is triggered. Called with no arguments | | onProgress | optional | A callback called on upload progress. Called with one arguments: a native ProgressEvent object | | onUpload | optional | A callback to be called on upload successful finish. Called with one argument: upload data object: { id: string, token: string, url: string } | | onError | optional | A callback to be called on upload error. Called with one argument: native Error object |

SharrDomUpload API

Class methods:

• constructor

  Returns new SharrDomUpload instance.

  | argument | required | description | |-|-|-| | options | optional | Options object. If not provided, default options will be used. Options can be also set later using setOptions instance method. |

Instance methods:

• setOptions(options)

  Allows for setting/updating option(s) for already created instance.

  Returns this.

  | argument | required | description | |-|-|-| | options | yes | Options object. Merged with existing instance options, what allows for updating only selection option(s). |

• enable()

  Activates the instance by attaching event listeners.

  Returns this.

• disable()

  Deactivates the instance (removes attached event listeners).

  Returns this.

• setFile(file[, source])

  Sets the file to be uploaded. Method called internally when DOM elements are provided in options. If no DOM elements are provided, this method can be called to manually set the file for upload, for example: from your own event listeners or uploading logic.

  Triggers calling onSelect callback.

  If autoSubmit option is set, calling setFile will also trigger submitting the file.

  Returns this.

  | argument | required | description | |-|-|-| | file | yes | Native File object. | | source | optional | The source event of the file. When called internally by automatic event listeners, this is populated with native Event object |

• async submit()

  Submits the file to the cloud. Automatically called internally if autoSubmit option is set. If not, needs to be called manually, after file has been set.

  Triggers calling onSubmit callback.

  Eventually triggers calling onProgress and onUpload or onError callbacks.

  Throws Error if called before file has been set.

  Returns a Promise that resolves with data also passed to onUpload callback.

Usage type: Import as ES Module in generic JS

import SharrDomUpload from '@sharr/dom-upload';

const inputElement = document.getElementById('file-input');
const dropContainerElement = document.getElementById('drop-container');
const submitButton = document.getElemenById('submit');

const sharr = new SharrDomUpload({
  clientToken: 'your clientToken here',
  inputElement,
  dropContainerElement,
  handlePaste: true,
  autoSubmit: false,
  onSelect: (file) => {
    // e.g.: display file preview here
  },
  onUpload: ({ id, url }) => {
    // e.g.: store file url for later
  }
});

// needed because we set `autoSubmit: false` in options
submitButton.addEventListener('click', () => {
  sharr.submit();
});

Usage type: React HOC

This package provides also convinient HOC to use with your React components.

Here's how to use it:

• Container file

  import React from 'react';
  import { withSharrUpload } from '@sharr/dom-upload';
  import { UploadComponent } from './UploadComponent';
  
  export function UploadContainer() {
    const SharrUploadComponent = withSharrUpload(UploadComponent);
  
    const onUpload = ({ id, url }) => {
      // your custom logic
    }
  
    return (
      <SharrUploadComponent
        clientToken='you clientToken here'
        onUpload={onUpload}
        autoSubmit
        handlePaste
      />
    );
  }

• Wrapped Component file

  Your wrapped component will need to handle some of the few specific props passed to it by SharrUpload HOC:

  | prop | type | required | description | |-|-|-|-| | onSelect | Function | optional () | Call this function to set a file for upload, e.g. as a onChange callback for <input type="file"> element in your component. | | onSubmit | Function | optional | Call this function if you're not using autoSubmit option and you want to submit the file from within wrapped component. | | dropContainerRef | React ref | optional () | Use this ref object in your render() method attaching it to the DOM element that you want to be a file drop zone. Use only when you need HOC to automatically handle setting file for upload by drag & drop. | | file | Native File object | optional | This prop is set after the file has been selected for upload | | uploading | boolean | optional | This prop is set to true after submitting the file or to false when upload finishes. | | progress | number | optional | Value between 0 and 1 indicating progress of the upload. Set 1 or multiple times after submitting the file. | | sharrId | number | optional | Sharr ID of the uploaded file, set after upload finishes. | | sharrToken | number | optional | Sharr TOKEN of the uploaded file, set after upload finishes. | | sharrUrl | string | optional | URL to the uploaded file, set after upload finishes. | | error | string | optional | Error message set in case of upload error (like exceeded size limit or network failure) |

  (*) - one of onSelect or dropContainerRef must be used for setting the file for upload.

  import React from 'react';
  
  export function UploadComponent({
    file,
    url,
    dropContainerRef,
    onSelect
  }) {
    return (
      <div ref={dropContainerRef}>
        <input type="file" onChange={onSelect}>
        <p>Selected file: {file ? file.name : 'none'}</p>
        <p>File URL: {url}</p>
      </div>
    );
  }

Author

👤 Sharr

Website: https://sharr.io