Features

• Resumable file uploads in React.
• Improved file upload management within the React component lifecycle.
• Lightweight and simple interface hooks.
• Manage Upload instances via context.
• TypeScript support.

Demo

Try out the use-tus demo.

Installation

Install the package using your package manager of choice.

npm install use-tus tus-js-client

Usage

Below is an example of how to use useTus.

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) 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, isUploading, error, remove } = useTus({ autoAbort, autoStart, uploadOptions, Upload });

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: TusHooksUploadFnOptions | undefined) (default: undefined)

  • Option to used by upload object that generated by that hooks.

• Upload (type: Upload | undefined) (default: undefined)

  • Option to specify customized own Upload class with this hooks.

uploadOptions

This option extends the UploadOptions provided by tus-js-client, allowing every callback to receive the upload instance as the final argument. For detailed type information on UploadOptions, see here.

Example:

setUpload(file, {
  onSuccess: (upload) => {
    console.log(upload.url)
  },
  onError: (error, upload) => {
    console.log(error)
    setTimeout(() => {
      upload.start()
    }, 1000)
  }
});

Returns

• upload (type: tus.Upload | undefined)

  • Used for resumable file uploads. Undefined unless setUpload is called.
  • For detailed usage, see here.

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

  • Function to create an Upload. uploadOptions properties are overwritten if options is specified.

• isSuccess (type: boolean)

  • Indicates if the upload was successful.

• isAborted (type: boolean)

  • Indicates if the upload was aborted.

• isUploading (type: boolean)

  • Indicates if an upload is in progress.

• error (type: Error | undefined)

  • Error when the upload fails.

• remove (type: () => void)

  • Function to reset states.

useTusStore hooks

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

useTusStore creates an object for resumable file uploads and stores it in a context. This is useful for handling uploads across components or pages.

[!NOTE] useTusStore requires TusClientProvider as a parent or higher element.

Arguments

• cacheKey (type: string)

  • Key associated with the Upload object created by setUpload.

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

  • Automatically abort uploads when useTusStore is unmounted.

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

  • Automatically start the upload after calling the setUpload function.

• uploadOptions (type: TusHooksUploadFnOptions | undefined, default: undefined)

  • Set options to be used by the upload object generated by this hook.

• Upload (type: Upload | undefined, default: undefined)

  • Specify a customized Upload class with this hook.

Returns

• upload (type: tus.Upload | undefined)

  • Used for resumable file uploads. Undefined unless setUpload is called.
  • Corresponds to the Upload associated with cacheKey in TusClientProvider.

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

  • Function to create an Upload. uploadOptions properties are overwritten if options is specified.

• isSuccess (type: boolean)

  • Indicates if the upload was successful.

• isAborted (type: boolean)

  • Indicates if the upload was aborted.

• isUploading (type: boolean)

  • Indicates if an upload is in progress.

• error (type: Error | undefined)

  • Error when the upload fails.

• remove (type: () => void)

  • Function to delete the Upload associated with cacheKey.

TusClientProvider

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

TusClientProvider stores Upload objects created with useTusStore.

Props

• defaultOptions (type: (file: tus.Upload['file']) => TusHooksUploadFnOptions | undefined)
  • Default options object used when creating new uploads. For more details, see here.

useTusClient

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

useTusClient retrieves and resets the state of TusClientProvider.

Returns

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

  • Upload information associated with cacheKey.

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

  • Remove the upload instance associated with cacheKey.

• reset (type: () => void)

  • Initialize the value of TusClientProvider.

Examples

Here are some examples of how to use use-tus.

Uploading a file

Use setUpload and upload.start functions 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) upload.start();
  }, [upload]);

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

[!TIP] You can also set autoStart to automatically start uploading files after setUpload is called.

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

Use the upload.abort function to abort an upload.

import { useTus } from 'use-tus'

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

  const handleAbort = useCallback(() => {
    if (upload) upload.abort();
  }, [upload]);

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

Default Options for Upload

Specify default options in defaultOptions props of the TusClientProvider.

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

const defaultOptions: DefaultOptions = (file) => ({
  endpoint: 'https://tusd.tusdemo.net/files/',
  metadata:
    file instanceof 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;

    // Uploads the selected file using default options.
    // Overrides if options are provided to setUpload.
    setUpload(file);
  }, [setUpload]);

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

Specify Upload Key

Specify cacheKey to associate uploads across components/pages.

import { useTusStore } from 'use-tus'

const SelectFileComponent = (file: File) => {
  const { setUpload } = useTusStore('upload-thumbnail');
  setUpload(file);
};

const UploadFileComponent = () => {
  const { upload } = useTusStore('upload-thumbnail');
  if (upload) upload.start();
};

License

MIT © kqito