kqito / use-tus

use-tus

React hooks for resumable file uploads using tus.

Features

• Resumable file uploads on react.
• Lightweight and simple interface hooks.
• Managing the Upload by using context.
• TypeScript support.

Demo

You can try the use-tus demo.

Installation

You can install the package from npm.

npm install use-tus tus-js-client

or

yarn add use-tus tus-js-client

Usage

We can use useTus as following.

import { useTus } from 'use-tus'

const Uploader = () => {
  const { upload, setUpload, isSuccess, error, remove } = useTus();

  const handleSetUpload = useCallback((event: ChangeEvent<HTMLInputElement>) => {
      const file = event.target.files.item(0);

      if (!file) {
        return;
      }

      setUpload(file, {
        endpoint: 'https://tusd.tusdemo.net/files/',
        metadata: {
          filename: file.name,
          filetype: file.type,
        },
      });
    },
    [setUpload]
  );

  const handleStart = useCallback(() => {
    if (!upload) {
      return;
    }

    // Start to upload the file.
    upload.start();
  }, [upload]);

  return (
    <div>
      <input type="file" onChange={handleSetUpload} />
      <button type="button" onClick={handleStart}>
        Upload
      </button>
    </div>
  );
};

API

useTus hooks

const { upload, setUpload, isSuccess, isAborted, error, remove } = useTus({ autoAbort, autoStart, uploadOptions });

useTus is a hooks that creates an object to perform Resumable file upload.

Arguments

• autoAbort (type: boolean | undefined) (default: true)

  • Whether or not to automatically abort uploads when useTus hooks is unmounted.

• autoStart (type: boolean | undefined) (default: false)

  • Whether or not to start upload the file after setUpload function.

• uploadOptions (type: UploadOptions | undefined) (default: undefined)

  • Option to used by upload object that generated by that hooks.
  • For detail type information of UploadOptions, please see here.

Returns

• upload (type: tus.Upload | undefined)

  • Object to be used when performing Resumable file upload.
  • This value is undefined unless the setUpload function called.
  • For detail usage, please see here

• setUpload (type: (file: tus.Upload['file'], options?: UploadOptions) => void)

  • Function to create an Upload.
  • The property specified in uploadOptions will be overwritten if property of options are speicified.

• isSuccess (type: boolean)

  • Whether the upload was successful or not.

• isAborted (type: boolean)

  • Whether the upload was aborted or not.

• error (type: Error | undefined)

  • Error when upload fails.

• remove (type: () => void)

  • Function to reset states.

useTusStore hooks

const { upload, setUpload, isSuccess, isAborted, error, remove } = useTusStore(cacheKey, { autoAbort, autoStart, uploadOptions  });

useTusStore is a hooks that creates an object for resumable file upload and stores it in a context.

This hooks is useful when you want to handle uploads across pages or components.

Note that using useTusStore hooks, the TusClientProvider must be specified as the parent or higher element.

Arguments

• cacheKey (type: string)

  • Specify the key associated with the Upload object is created by setUpload function.

• autoAbort (type: boolean | undefined) (default: true)

  • Whether or not to automatically abort uploads when useTusStore hooks is unmounted.

• autoStart (type: boolean | undefined) (default: false)

  • Whether or not to start upload the file after setUpload function.

• uploadOptions (type: UploadOptions | undefined) (default: undefined)

  • Option to used by upload object that generated by that hooks.
  • For detail type information of UploadOptions, please see here.

Returns

• upload (type: tus.Upload | undefined)

  • Object to be used when performing Resumable file upload.
  • This value of the Upload associated with the cacheKey in the TusClientProvider. If not present, undefined.
  • For detail usage, please see here

• setUpload (type: (file: tus.Upload['file'], options?: tus.Upload['options']) => void)

  • Function to create an Upload.
  • The property specified in uploadOptions will be overwritten if property of options are speicified.

• isSuccess (type: boolean)

  • Whether the upload was successful or not.

• isAborted (type: boolean)

  • Whether the upload was aborted or not.

• error (type: Error | undefined)

  • Error when upload fails.

• remove (type: () => void)

  • Function to delete the Upload associated with cacheKey.

TusClientProvider

() => (
  <TusClientProvider defaultOptions={defaultOptions}>
    {children}
  </TusClientProvider>
)

TusClientProvider is the provider that stores the Upload with useTusStore hooks.

Props

• defaultOptions (type: (file: tus.Upload['file']) => UploadOptions | undefined)
  • An object containing the default options used when creating a new upload. detail

useTusClient

const { state, removeUpload, reset } = useTusClient();

useTusClient is a hooks that can be used to retrieve and reset the state of a TusClientProvider.

Returns

• state (type: { [cacheKey: string]: UploadState | undefined })

  • Upload information associated with cacheKey

• removeUpload (type: (cacheKey: string) => void)

  • Remove the upload instance associated with the specified cacheKey.

• reset (type: () => void)

  • Initialize the value of TusClientProvider

Examples

The following are some example of how to use use-tus.

Uploading a file

The setUpload and upload.start functions can be used to perform resumable file uploads.

import { useTus } from 'use-tus'

const Uploader = () => {
  const { upload, setUpload } = useTus();

  const handleSetUpload = useCallback((event: ChangeEvent<HTMLInputElement>) => {
      const file = event.target.files.item(0);

      if (!file) {
        return;
      }

      setUpload(file, {
        endpoint: 'https://tusd.tusdemo.net/files/',
        metadata: {
          filename: file.name,
          filetype: file.type,
        },
      });
    },
    [setUpload]
  );

  const handleStart = useCallback(() => {
    if (!upload) {
      return;
    }

    // Start upload the file.
    upload.start();
  }, [upload]);

  return (
    <div>
      <input type="file" onChange={handleSetUpload} />
      <button type="button" onClick={handleStart}>
        Upload
      </button>
    </div>
  );
};

It is also possible to automatically upload files after setUpload by specifying the autoStart option.

import { useTus } from 'use-tus'

const Uploader = () => {
  const { upload, setUpload } = useTus({ autoStart: true });

  const handleSetUpload = useCallback((event: ChangeEvent<HTMLInputElement>) => {
      const file = event.target.files.item(0);

      if (!file) {
        return;
      }

      setUpload(file, {
        endpoint: 'https://tusd.tusdemo.net/files/',
        metadata: {
          filename: file.name,
          filetype: file.type,
        },
      });
    },
    [setUpload]
  );
  return (
    <input type="file" onChange={handleSetUpload} />
  );
};

Aborting a file upload

You can abort the upload by using the upload.abort function.

import { useTus } from 'use-tus'

const Aborter = () => {
  const { upload } = useTus();

  const handleAbort = useCallback(() => {
    if (!upload) {
      return;
    }

    upload.abort();
  }, [upload]);

  return (
    <div>
      <button type="button" onClick={handleAbort}>
        Abort
      </button>
    </div>
  );
};

You can also specify the autoAbort option to automatically stop uploads when unmounting hooks.

import { useTus } from 'use-tus'

const Uploader = () => {
  const { upload, setUpload } = useTus({ autoAbort: true });

  // omitted...
};

Default options of upload

You can specify default options in the defaultOptions props of the TusClientProvider.

import { useTusStore, DefaultOptions, TusClientProvider } from 'use-tus'

const defaultOptions: DefaultOptions = (contents) => {
  const file = contents instanceof File ? contents : undefined;

  return {
    endpoint: 'https://tusd.tusdemo.net/files/',
    metadata: file
      ? {
          filename: file.name,
          filetype: file.type,
        }
      : undefined,
  };
};

const App = () => (
  <TusClientProvider defaultOptions={defaultOptions}>
    <Uploader />
  </TusClientProvider>
);

const Uploader = () => {
  const { setUpload } = useTusStore('cacheKey', { autoStart: true });

  const handleSetUpload = useCallback((event: ChangeEvent<HTMLInputElement>) => {
      const file = event.target.files.item(0);

      if (!file) {
        return;
      }

      // You no longer need to specify the options associated with upload.
      // If specified, it will override defaultOptions.
      setUpload(file);
    },
    [setUpload]
  );

  return (
    <div>
      <input type="file" onChange={handleSetUpload} />
    </div>
  );
};

Specify upload key

If you specify cacheKey as an argument to useTusStore, you can get the upload associated with it. This is useful for cross-page file uploads.

const SelectFileComponent = (file: File) => {
  // Create upload accosiated with 'upload-thumbnail' key
  const { setUpload } = useTusStore('upload-thumbnail')

  setUpload(file)
}

const UploadFileComponent = () => {
  const { upload } = useTusStore('upload-thumbnail')

  upload.start()
}

License

MIT © kqito