React hooks for resumable file uploads using tus.

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

You can try the use-tus demo.

You can install the package from npm.

npm install use-tus tus-js-client

or

yarn add use-tus tus-js-client

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>
  );
};

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.

• 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.

This option extends the UploadOptions provided by tus-js-client, but it has been extended so that every callback can receive the upload instance as the final argument.

For detail type information of UploadOptions, please see here.

e.g.

setUplaod(file, {
  onSuccess: (upload) => {
    console.log(upload.url)
  },
  onError: (error, upload) => {
    console.log(error)

    setTimeout(() => {
      upload.start()
    }, 1000)
  }
})

• 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?: TusHooksUploadFnOptions) => 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.

• isUploading (type: boolean)

  • Indicates if an uploading is in progress or not.

• error (type: Error | undefined)

  • Error when upload fails.

• remove (type: () => void)

  • Function to reset states.

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

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.

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

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

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

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

• upload (type: tus.Upload | undefined)
  • Object to be used when performing Resumable file upload.
  • This value is undefined unless the setUpload function called.

• 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.

• isUploading (type: boolean)

  • Indicates if an uploading is in progress or not.

• error (type: Error | undefined)

  • Error when upload fails.

• remove (type: () => void)

  • Function to delete the Upload associated with cacheKey.

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

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

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

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

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

• 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

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

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} />
  );
};

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...
};

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>
  );
};

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()
}

MIT © kqito