include, same-origin, or{' '}
omit.
),
required: false,
},
retry: {
description: 'Number of times to retry network requests that fail.',
type: 'number',
default: '0',
required: false,
},
retryDelay: {
description: 'Delay in milliseconds between retries.',
type: 'number',
default: '0',
required: false,
},
}}
/>
## Events
### On before upload
Callback that is called before requesting the pre-signed URLs. Use this to modify the files before uploading them, like resizing or compressing. You can also throw an error to reject the file upload.
```tsx
useUploadFiles({
route: 'images',
onBeforeUpload: ({ files }) => {
// rename all files
return files.map(
(file) => new File([file], 'renamed-' + file.name, { type: file.type })
);
},
});
```
### On upload begin
Event that is called before the files start being uploaded to S3. This happens after the server responds with the pre-signed URLs.
```tsx
useUploadFiles({
route: 'images',
onUploadBegin: ({ files, metadata }) => {
console.log('Upload begin');
},
});
```
### On upload progress
Event that is called when a file upload progress changes.
```tsx
useUploadFiles({
route: 'images',
onUploadProgress: ({ file }) => {
console.log(`${file.name} upload progress: ${file.progress * 100}%`);
},
});
```
### On upload complete
Event that is called after files are successfully uploaded.
```tsx
// This event is called even if some files fail to upload, but some succeed.
// This event is not called if all files fail to upload.
useUploadFiles({
route: 'images',
onUploadComplete: ({ files, failedFiles, metadata }) => {
console.log(`${files.length} files uploaded`);
},
});
```
### On upload fail
Event that is called after the entire upload if a file fails to upload.
```tsx
// This event is called even if some files succeed to upload, but some fail.
// This event is not called if all files succeed.
useUploadFiles({
route: 'images',
onUploadFail: ({ succeededFiles, failedFiles, metadata }) => {
console.log('Some or all files failed to upload');
},
});
```
### On error
Event that is called if a critical error occurs before the upload to S3, and no files were able to be uploaded. For example, if your server is unreachable.
```tsx
useUploadFiles({
route: 'images',
onError: (error) => {
console.log(error.message);
},
});
```
include, same-origin, or{' '}
omit.
),
required: false,
},
retry: {
description: 'Number of times to retry network requests that fail.',
type: 'number',
default: '0',
required: false,
},
retryDelay: {
description: 'Delay in milliseconds between retries.',
type: 'number',
default: '0',
required: false,
},
}}
/>
## Events
### On before upload
Callback that is called before requesting the pre-signed URL. Use this to modify the file before uploading it, like resizing or compressing. You can also throw an error to reject the file upload.
```tsx
useUploadFile({
route: 'profile',
onBeforeUpload: ({ file }) => {
// rename the file
return new File([file], 'renamed-' + file.name, { type: file.type });
},
});
```
### On upload begin
Event that is called before the file starts being uploaded to S3. This happens after the server responds with the pre-signed URL.
```tsx
useUploadFile({
route: 'profile',
onUploadBegin: ({ file, metadata }) => {
console.log('Upload begin');
},
});
```
### On upload progress
Event that is called when the file upload progress changes.
```tsx
useUploadFile({
route: 'profile',
onUploadProgress: ({ file }) => {
console.log(`Upload progress: ${file.progress * 100}%`);
},
});
```
### On upload complete
Event that is called after the file is successfully uploaded.
```tsx
useUploadFile({
route: 'profile',
onUploadComplete: ({ file, metadata }) => {
console.log('File uploaded');
},
});
```
### On error
Event that is called if the upload fails.
```tsx
useUploadFile({
route: 'profile',
onError: (error) => {
console.log(error.message);
},
});
```
image/*.
),
type: 'string[]',
default: 'All file types allowed',
required: false,
},
maxFileSize: {
description: 'The maximum file size in bytes.',
type: 'number',
default: '5242880 (5MB)',
required: false,
},
signedUrlExpiresIn: {
description: 'The time in seconds the upload pre-signed URL is valid.',
type: 'number',
default: '120 (2 minutes)',
required: false,
},
clientMetadataSchema: {
description:
'Schema for validating metadata sent from the client. Use any validation library compatible with Standard Schema, like Zod.',
type: 'object',
required: false,
},
}}
/>
## Callbacks
When defining a route, you may want to run code before or after the upload. You can do this by using the callbacks.
### Before upload
The `onBeforeUpload` callback is called before pre-signed URLs are generated. Use this to run custom logic before uploading files, such as auth and rate-limiting.
The request, files, and metadata sent from the client are available.
```ts
route({
onBeforeUpload: async ({ req, files, clientMetadata }) => {
const user = await auth();
if (!user) {
throw new RejectUpload('Not logged in!');
}
return {
generateObjectInfo: ({ file }) => ({
key: `${user.id}/${file.name}`,
}),
bucketName: 'another-bucket',
};
},
});
```
key, metadata, acl,{' '}
storageClass, cacheControl.
),
required: false,
},
metadata: {
description: (
<>
Metadata to be passed to the onAfterSignedUrl callback.
),
type: 'object',
required: false,
},
bucketName: {
description:
'If you wish to upload to a bucket different from the one defined in the router, you can specify its name here.',
type: 'string',
required: false,
},
}}
/>
### After generating pre-signed URL
The `onAfterSignedUrl` callback is called after the pre-signed URLs are generated. Use this to run custom logic after the URL is generated, such as logging and saving data.
In addition to all previous data, metadata from the `onBeforeUpload` callback is also available.
```ts
route({
onAfterSignedUrl: async ({ req, files, metadata, clientMetadata }) => {
// the files now have the objectInfo property
return {
metadata: {
example: '123',
},
};
},
});
```
You can return an object with the following properties:
image/*.
),
type: 'string[]',
default: 'All file types allowed',
required: false,
},
maxFileSize: {
description: 'The maximum file size in bytes.',
type: 'number',
default: '5242880 (5MB)',
required: false,
},
signedUrlExpiresIn: {
description: 'The time in seconds the upload pre-signed URL is valid.',
type: 'number',
default: '120 (2 minutes)',
required: false,
},
clientMetadataSchema: {
description:
'Schema for validating metadata sent from the client. Use any validation library compatible with Standard Schema, like Zod.',
type: 'object',
required: false,
},
}}
/>
## Callbacks
When defining a route, you may want to run code before or after the upload. You can do this by using the callbacks.
### Before upload
The `onBeforeUpload` callback is called before the pre-signed URL is generated. Use this to run custom logic before uploading a file, such as auth and rate-limiting.
The request, file, and metadata sent from the client are available.
```ts
route({
onBeforeUpload: async ({ req, file, clientMetadata }) => {
const user = await auth();
if (!user) {
throw new RejectUpload('Not logged in!');
}
return {
objectInfo: {
key: user.id,
},
bucketName: 'another-bucket',
};
},
});
```
key, metadata, acl,{' '}
storageClass, cacheControl.
),
required: false,
},
metadata: {
description: (
<>
Metadata to be passed to the onAfterSignedUrl callback.
),
type: 'object',
required: false,
},
bucketName: {
description:
'If you wish to upload to a bucket different from the one defined in the router, you can specify its name here.',
type: 'string',
required: false,
},
}}
/>
### After generating pre-signed URL
The `onAfterSignedUrl` callback is called after the pre-signed URL is generated. Use this to run custom logic after the URL is generated, such as logging and saving data.
In addition to all previous data, metadata from the `onBeforeUpload` callback is also available.
```ts
route({
onAfterSignedUrl: async ({ req, file, metadata, clientMetadata }) => {
// the file now has the objectInfo property
return {
metadata: {
example: '123',
},
};
},
});
```
You can return an object with the following properties:
Drop files here
{progress.name}
{formatBytes(progress.size)}
Failed
) : (Completed
)}Drop files here