use-tus
React hooks for resumable file uploads using tus-js-client.
Features
- Resumable file uploads on react.
- Managing the Upload by using context.
- One dependency (tus-js-client).
- TypeScript support.
Demo
You can try the use-tus demo.
Installation
You can install the package from npm.
npm install use-tus
or
yarn add use-tus
Usage
We can use useTus
as following.
import { useTus, TusClientProvider } from 'use-tus'
const App = () => (
<TusClientProvider>
<Uploader />
</TusClientProvider>
);
const Uploader = () => {
const { upload, setUpload, isSuccess, error, remove } = useTus();
const handleSetUpload = useCallback(
(event) => {
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>
);
};
API
useTus
hooks
const { upload, setUpload, isSuccess, error, remove } = useTus({ cacheKey, autoAbort });
useTus
is a hooks to get or create an Upload
of tus.
Arguments
-
cacheKey
(type:string | undefined
)- Specify the key associated with the
Upload
if it's undefined, a random string will be specified.
- Specify the key associated with the
-
autoAbort
(type:boolean | undefined
) (default: true)- Whether or not to automatically abort uploads when useTus hooks is unmounted.
Returns
-
upload
(type:tus.Upload | undefined
)- The value of the
Upload
associated with the cacheKey in the TusClientProvider. If not present, undefined.
- The value of the
-
setUpload
(type:(file: tus.Upload['file'], options?: tus.Upload['options']) => void
)- Function to create an
Upload
and store it in TusClientProvider.
- Function to create an
-
isSuccess
(type:boolean
)- Whether the upload was successful or not.
-
error
(type:Error | undefined
)- Error when upload fails.
-
remove
(type:() => void
)- Function to delete the
Upload
associated with cacheKey.
- Function to delete the
TusClientProvider
() => (
<TusClientProvider>
{children}
</TusClientProvider>
)
TusClientProvider
is the provider that stores the Upload
with useTus
hooks.
In order to use useTus
, you need to set TusClientProvider
.
Props
-
canStoreURLs
(type:boolean | undefined
)- A boolean indicating whether the current environment allows storing URLs enabling the corresponding upload to be resumed. detail
-
defaultOptions
(type:tus.DefaltOptions | undefined
)- An object containing the default options used when creating a new upload. detail
Examples
Specify upload key
If you specify cacheKey
as an argument to useTus, you can get the upload
associated with it. This is useful for resuming uploads, etc.
const SelectFileComponent = (file) => {
// Create upload accosiated with 'upload-thumbnail' key
const { setUpload } = useTus({cacheKey: 'upload-thumbnail'})
setUpload(file)
}
const UploadFileComponent = () => {
const { upload } = useTus({cacheKey: 'upload-thumbnail'})
upload.start()
}