use-tus

use-tus

React hooks for resumable file uploads using tus.

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.

``sh
npm install use-tus tus-js-client
`

Usage


Below is an example of how to use useTus.

`tsx
import { useTus } from 'use-tus'

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

const handleSetUpload = useCallback((event: ChangeEvent) => {
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 (



);
};
`

API

$3

`tsx
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.

$3


- 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:

`ts
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.

$3

`tsx
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.

$3

`tsx
() => (

{children}

)
`

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.

$3

`tsx
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.

$3

Use setUpload and upload.start functions to perform resumable file uploads.

`tsx
import { useTus } from 'use-tus'

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

const handleSetUpload = useCallback((event: ChangeEvent) => {
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 (



);
};
`

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

`tsx
import { useTus } from 'use-tus'

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

const handleSetUpload = useCallback((event: ChangeEvent) => {
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 (

);
};
`

$3


Use the upload.abort function to abort an upload.

`tsx
import { useTus } from 'use-tus'

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

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

return (



);
};
`

$3

Specify default options in defaultOptions props of the TusClientProvider.

`tsx
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 = () => (



);

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

const handleSetUpload = useCallback((event: ChangeEvent) => {
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 ;
};
`

$3


Specify cacheKey to associate uploads across components/pages.

`tsx
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