1.3.0 • Public • Published

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


npm install @sharr/dom-upload



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


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 optional
default: 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 optional
default: false
Set true to enable auto-submitting the file after selecting
autoEnable optional
default: 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',
  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', () => {

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 (
          clientToken='you clientToken here'
  • 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({
    }) {
      return (
        <div ref={dropContainerRef}>
          <input type="file" onChange={onSelect}>
          <p>Selected file: {file ? file.name : 'none'}</p>
          <p>File URL: {url}</p>


👤 Sharr

Website: https://sharr.io


npm i @sharr/dom-upload

DownloadsWeekly Downloads






Unpacked Size

31.1 kB

Total Files


Last publish


  • jacekzlowocki