React hooks for resumable file uploads using tus-js-client
npm install use-tus
React hooks for resumable file uploads using tus.
``sh`
npm install use-tus tus-js-client
.`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();
};
``