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

Single file

To upload single files, use the useUploadFile hook.

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

Multiple files

To upload multiple files at once, use the useUploadFiles hook.

import { useUploadFiles } from 'better-upload/client';
 
export function MyComponent() {
  const {
    upload,
    uploadedFiles,
    failedFiles,
    progresses,
    isPending,
    isSuccess,
    isError,
    error,
    reset,
  } = useUploadFiles({
    route: 'demo',
  });
 
  return (
    <input
      type="file"
      multiple
      onChange={(e) => {
        if (e.target.files) {
          upload(e.target.files);
        }
      }}
    />
  );
}

Sequential upload

With multiple files, you can also upload sequentially, rather than in parallel. This can be useful to reduce the load on the client and S3 server, however, it will take longer to upload all files.

useUploadFiles({
  route: 'demo',
  sequential: true,
});

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 in parallel.

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 when the file starts being uploaded to the S3 bucket. Happens after your server responds with a pre-signed URL.

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

On upload progress

Event that is called when the file upload progress changes.

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

On upload complete

Event that is called after the file has been successfully uploaded. If some files failed to upload, they will be in the failedFiles array.

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

On upload error

Event that is called if the upload fails. This can be called more than once for multiple files.

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

On upload settled

Event that is called when the file upload has settled, regardless of success or failure.

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

Error handling

Failed multiple files

When uploading multiple files, although rare, some files may fail to upload. In this case, the failedFiles array will contain the files that failed to upload.