uploadthing/client
The UploadThing Client module provides utilities for working files in your application and communicating with your backend file router.
uploadFiles
This function is used to perform client side uploads by requesting presigned URLs from your backend file router, and then uploading the files to the storage provider.
Use the genUploader
factory function to generate a typed function that matches
the signature of your file router, which will allow autocompletion and type
checking on endpoint, route input and callback data types.
import { genUploader } from "uploadthing/client";
import type { UploadRouter } from "~/server/uploadthing";
export const { uploadFiles } = genUploader<UploadRouter>();
const response = await uploadFiles("routeEndpoint", {
files: [],
});
Parameters
The first parameter is the route endpoint to upload to, and the second parameter is an options object:
- Name
- files
- Type
- RequiredSince 5.0
- Description
An array of files to upload.
File[]
- Name
- input
- Type
- Since 5.0
- Description
Input JSON data matching your validator set on the FileRoute to send with the request.
TInput
- Name
- headers
- Type
- Since 5.1
- Description
Headers to be sent along the request to request the presigned URLs. Useful for authentication outside full-stack framework setups.
HeadersInit | () => HeadersInit
- Name
- signal
- Type
- Since 6.7
- Description
An abort signal to abort the upload.
AbortSignal
- Name
- onUploadBegin
- Type
- Since 5.4
- Description
Callback function called after the presigned URLs have been retrieved, just before the file is uploaded. Called once per file.
({ file: string }) => void
- Name
- onUploadProgress
- Type
- Since 6.4
- Description
Callback function that gets continuously called as the file is uploaded to the storage provider.
({ file, progress }) => void
Returns
The function returns a Promise
that resolves to an array of objects:
- Name
- name
- Type
- Description
The name of the file.
string
- Name
- size
- Type
- Description
The size of the file in bytes.
number
- Name
- type
- Type
- Description
The type of the file.
string
- Name
- key
- Type
- Description
The file key of the file.
string | null
- Name
- url
- Type
- Description
The url of the file.
string
- Name
- customId
- Type
- Description
The custom id of the file, if provided on upload.
string | null
- Name
- serverData
- Type
- Description
The data returned from the
onUploadComplete
callback on the file route. This will benull
ifRouteOptions.awaitServerData
isn't enabled.
Generic
createUpload
Create a resumable upload. Resumable uploads allows you to start an upload, pause it, and then resume it at a later time. As long as the presigned URL is valid, you can continue the upload from where it left off.
As for uploadFiles
, use the genUploader
factory function to generate a typed
function that matches the signature of your file router, which will allow
autocompletion and type checking on endpoint, route input and callback data
types.
import { genUploader } from "uploadthing/client";
import type { UploadRouter } from "~/server/uploadthing";
export const { createUpload } = genUploader<UploadRouter>();
// Create the upload. The files will start uploading immediately.
const { pauseUpload, resumeUpload, done } = createUpload("routeEndpoint", {
files: [],
});
// Pause the upload of a file
pauseUpload(file);
// Resume the upload of a file
resumeUpload(file);
// Await the completion of all files
const files = await done();
Parameters
The first parameter is the route endpoint to upload to, and the second parameter is an options object:
- Name
- files
- Type
- RequiredSince 7.0
- Description
An array of files to upload.
File[]
- Name
- input
- Type
- Since 7.0
- Description
Input JSON data matching your validator set on the FileRoute to send with the request.
TInput
- Name
- headers
- Type
- Since 7.0
- Description
Headers to be sent along the request to request the presigned URLs. Useful for authentication outside full-stack framework setups.
HeadersInit | () => HeadersInit
- Name
- onUploadProgress
- Type
- Since 7.0
- Description
Callback function that gets continuously called as the file is uploaded to the storage provider.
(progress) => void
Returns
- Name
- pauseUpload
- Type
- Since 7.0
- Description
Pause the upload of a file. If no file is provided, all files will be paused.
(file?: File) => void
- Name
- resumeUpload
- Type
- Since 7.0
- Description
Resume the upload of a file. If no file is provided, all files will be resumed.
(file?: File) => void
- Name
- done
- Type
- Since 7.0
- Description
Await the completion of the upload of a file. If no file is provided, all files will be awaited. The returned object is the same as the one returned by
uploadFiles
. If a file is provided, the function returns an object, else it returns an array.
(file?: File) => Promise<MaybeArray<UploadedFileResponse>>
generateClientDropzoneAccept
Generate an accepted object that can be passed to the accept
prop of a
useDropzone
hook or Dropzone
component.
Parameters
- Name
- fileTypes
- Type
- Required
- Description
The route config to generate the accept props for.
string[]
Returns
object
generateMimeTypes
Generate an array of accepted mime types given a route config.
Parameters
- Name
- config
- Type
- Required
- Description
The route config to generate the accept props for.
ExpandedRouteConfig
Returns
string[]
generatePermittedFileTypes
Utility function to generate accept props for a <input type="file">
element.
Parameters
- Name
- config
- Type
- Required
- Description
The route config to generate the accept props for.
ExpandedRouteConfig
Returns
- Name
- fileTypes
- Type
- Description
The route config to generate the accept props for.
string[]
- Name
- multiple
- Type
- Description
Whether the accept props should be for multiple files.
boolean
isValidSize
This function is used to validate that a file is of a valid size given a route config.
Parameters
- Name
- file
- Type
- Required
- Description
The size of the file to validate.
File
- Name
- maxSize
- Type
- Required
- Description
The maximum size of the file to validate.
number
Returns
boolean
isValidType
This function is used to validate that a file is of a valid type given a route config.
Parameters
- Name
- file
- Type
- Required
- Description
The type of the file to validate.
File
- Name
- allowedTypes
- Type
- Required
- Description
The allowed types of the file to validate.
string[]
Returns
boolean