@hishprorg/sint-sit
React hooks for resumable file uploads using tus.
Features
- Resumable file uploads on react.
- Lightweight and simple interface hooks.
- Managing the Upload by using context.
- TypeScript support.
Demo
You can try the @hishprorg/sint-sit demo.
Installation
You can install the package from npm.
npm install @hishprorg/sint-sit tus-js-client
or
yarn add @hishprorg/sint-sit tus-js-client
Usage
We can use useTus
as following.
import { useTus } from '@hishprorg/sint-sit'
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;
}
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, 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.
About uploadOptions
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)
}
})
Returns
-
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
)
-
remove
(type: () => void
)
- Function to reset states.
useTusStore
hooks
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.
Arguments
-
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.
Returns
upload
(type: tus.Upload | undefined
)
- Object to be used when performing Resumable file upload.
- This value is undefined unless the
setUpload
function called.
Returns
-
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
)
-
remove
(type: () => void
)
- Function to delete the
Upload
associated with cacheKey.
TusClientProvider
() => (
<TusClientProvider defaultOptions={defaultOptions}>
{children}
</TusClientProvider>
)
TusClientProvider
is the provider that stores the Upload
with useTusStore
hooks.
Props
defaultOptions
(type: (file: tus.Upload['file']) => TusHooksUploadFnOptions | undefined
)
- An object containing the default options used when creating a new upload. detail
useTusClient
const { state, removeUpload, reset } = useTusClient();
useTusClient
is a hooks that can be used to retrieve and reset the state of a TusClientProvider
.
Returns
Examples
The following are some example of how to use @hishprorg/sint-sit
.
Uploading a file
The setUpload and upload.start
functions can be used to perform resumable file uploads.
import { useTus } from '@hishprorg/sint-sit'
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;
}
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 '@hishprorg/sint-sit'
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} />
);
};
Aborting a file upload
You can abort the upload by using the upload.abort
function.
import { useTus } from '@hishprorg/sint-sit'
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 '@hishprorg/sint-sit'
const Uploader = () => {
const { upload, setUpload } = useTus({ autoAbort: true });
};
Default options of upload
You can specify default options in the defaultOptions
props of the TusClientProvider
.
import { useTusStore, DefaultOptions, TusClientProvider } from '@hishprorg/sint-sit'
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;
}
setUpload(file);
},
[setUpload]
);
return (
<div>
<input type="file" onChange={handleSetUpload} />
</div>
);
};
Specify upload key
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) => {
const { setUpload } = useTusStore('upload-thumbnail')
setUpload(file)
}
const UploadFileComponent = () => {
const { upload } = useTusStore('upload-thumbnail')
upload.start()
}
License
MIT © kqito