https://github.com/kqito/use-tus
React hooks for resumable file uploads using tus
https://github.com/kqito/use-tus
hooks react react-hooks tus tus-js-client
Last synced: 5 months ago
JSON representation
React hooks for resumable file uploads using tus
- Host: GitHub
- URL: https://github.com/kqito/use-tus
- Owner: kqito
- License: mit
- Created: 2021-04-02T11:10:47.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2025-08-20T12:49:59.000Z (10 months ago)
- Last Synced: 2025-09-23T18:09:31.602Z (9 months ago)
- Topics: hooks, react, react-hooks, tus, tus-js-client
- Language: TypeScript
- Homepage: https://kqito.github.io/use-tus/?path=/story/usetus--basic
- Size: 2.47 MB
- Stars: 117
- Watchers: 2
- Forks: 8
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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](https://github.com/tus/tus-js-client/blob/master/docs/api.md#tusuploadfile-options) instances via context.
- TypeScript support.
## Demo
Try out the [use-tus demo](https://kqito.github.io/use-tus/?path=/story/usetus--basic).
## 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 (
Upload
);
};
```
## API
### `useTus` hooks
```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.
### 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](https://github.com/tus/tus-js-client/blob/master/lib/index.d.ts#L22).
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](https://github.com/tus/tus-js-client#example).
- `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
```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`.
### `TusClientProvider`
```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](https://github.com/tus/tus-js-client/blob/master/docs/api.md#tusdefaultoptions).
### `useTusClient`
```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`.
### Uploading a file
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 (
Upload
);
};
```
> [!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 (
);
};
```
### Aborting a File Upload
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 (
Abort
);
};
```
### Default Options for Upload
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 ;
};
```
### Specify Upload Key
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](./LICENSE)