Client Hooks

Better Upload provides React hooks that allow you to easily upload files using pre-signed URLs. Multipart uploads are managed automatically, in case you enable them in the server.

Usage

import { useUploadFile } from 'better-upload/client';
 
export function MyComponent() {
  const {
    upload,
    uploadAsync,
    reset,
    uploadedFile,
    progress,
    isPending,
    isSettled,
    isError,
    isSuccess,
    error,
    metadata,
    control, // for use in pre-built components
  } = useUploadFile({
    route: 'demo',
  });
 
  return (
    <input
      type="file"
      onChange={(e) => {
        if (e.target.files?.[0]) {
          upload(e.target.files[0]);
        }
      }}
    />
  );
}

Options

Both hooks have the following options:

• api: The API endpoint to use for uploading files. Default is /api/upload.
• route: The route to use for uploading files. Needs to match the upload route in the server.
• multipartBatchSize: The number of parts to upload at the same time when uploading a multipart file. By default, all parts are uploaded simultaneously.
• signal: The AbortSignal to use for cancelling the upload.
• headers: The headers to send with the pre-signed URL request to your server.

For multiple files, you can also specify:

• uploadBatchSize: The number of files to upload in parallel. By default, all files are uploaded simultaneously.

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.

useUploadFile({
  route: 'demo',
  onBeforeUpload: ({ file }) => {
    // rename the file
    return 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 URL.

useUploadFile({
  route: 'demo',
  onUploadBegin: ({ file, metadata }) => {
    console.log('Upload begin');
  },
});

On upload progress

Event that is called when a file upload progress changes.

useUploadFile({
  route: 'demo',
  onUploadProgress: ({ file }) => {
    console.log(`Upload progress: ${file.progress * 100}%`);
  },
});

On upload complete

Event that is called after files are successfully uploaded.

useUploadFile({
  route: 'demo',
  onUploadComplete: ({ file, metadata }) => {
    console.log('File uploaded');
  },
});

On upload fail

Event that is called after the entire upload if a file fails to upload.

// Use onError instead of this event for single file uploads

On error

Event that is called if:

• For multiple files: A critical error occurs before the upload to S3, and no files were able to be uploaded. For example, if your server is unreachable.
• For single file: The upload fails.

Also called if some input is invalid. For example, if no files were selected.

useUploadFile({
  route: 'demo',
  onError: (error) => {
    console.log(error.message);
  },
});

On upload settle

Event that is called after the upload settles (either successfully completed or an error occurs).

useUploadFile({
  route: 'demo',
  onUploadSettle: ({ file, metadata }) => {
    console.log('Upload settled');
  },
});