@sharr/dom-upload v1.3.0

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.

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