# Helpers (/docs/helpers-client)



<PageSelect
  pages="[
  {
    href: '/docs/helpers-server',
    title: 'Server-side',
    description: 'Helpers for your router and server.',
  },
  {
    href: '/docs/helpers-client',
    title: 'Client-side',
    description: 'Helpers for your frontend.',
  },
]"
/>

Format bytes [#format-bytes]

Format a number of bytes into a human-readable string.

```ts
import { formatBytes } from '@better-upload/client/helpers';

formatBytes(1000); // "1 kB"
formatBytes(1000, { decimalPlaces: 2 }); // "1.00 kB"

formatBytes(1024, { si: false }); // "1 KiB"
formatBytes(1024, { decimalPlaces: 2, si: false }); // "1.00 KiB"
```


# Helpers (/docs/helpers-server)



<PageSelect
  pages="[
  {
    href: '/docs/helpers-server',
    title: 'Server-side',
    description: 'Helpers for your router and server.',
  },
  {
    href: '/docs/helpers-client',
    title: 'Client-side',
    description: 'Helpers for your frontend.',
  },
]"
/>

S3 Clients [#s3-clients]

Better Upload has built-in clients for popular S3-compatible storage services, like AWS S3 and Cloudflare R2. Suggest a new client by [opening an issue](https://github.com/Nic13Gamer/better-upload/issues).

<CodeBlockTabs defaultValue="AWS S3">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="AWS S3">
      AWS S3
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Cloudflare R2">
      Cloudflare R2
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Tigris">
      Tigris
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Backblaze B2">
      Backblaze B2
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="DigitalOcean Spaces">
      DigitalOcean Spaces
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Wasabi">
      Wasabi
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="MinIO">
      MinIO
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Linode">
      Linode
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Custom">
      Custom
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="AWS S3">
    ```ts
    import { aws } from '@better-upload/server/clients';

    const s3 = aws({
      accessKeyId: 'your-access-key-id',
      secretAccessKey: 'your-secret-access-key',
      region: 'us-east-1',
    });
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Cloudflare R2">
    ```ts
    import { cloudflare } from '@better-upload/server/clients';

    const s3 = cloudflare({
      accountId: 'your-account-id',
      accessKeyId: 'your-access-key-id',
      secretAccessKey: 'your-secret-access-key',
    });
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Tigris">
    ```ts
    import { tigris } from '@better-upload/server/clients';

    const s3 = tigris({
      accessKeyId: 'your-access-key-id',
      secretAccessKey: 'your-secret-access-key',
      endpoint: '...', // optional
    });
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Backblaze B2">
    ```ts
    import { backblaze } from '@better-upload/server/clients';

    const s3 = backblaze({
      region: 'your-backblaze-region',
      applicationKeyId: 'your-application-key-id',
      applicationKey: 'your-application-key',
    });
    ```
  </CodeBlockTab>

  <CodeBlockTab value="DigitalOcean Spaces">
    ```ts
    import { digitalOcean } from '@better-upload/server/clients';

    const s3 = digitalOcean({
      region: 'your-spaces-region',
      key: 'your-spaces-key',
      secret: 'your-spaces-secret',
    });
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Wasabi">
    ```ts
    import { wasabi } from '@better-upload/server/clients';

    const s3 = wasabi({
      region: 'your-wasabi-region',
      accessKeyId: 'your-access-key-id',
      secretAccessKey: 'your-secret-access-key',
    });
    ```
  </CodeBlockTab>

  <CodeBlockTab value="MinIO">
    ```ts
    import { minio } from '@better-upload/server/clients';

    const s3 = minio({
      region: 'your-minio-region',
      endpoint: 'https://minio.example.com',
      accessKeyId: 'your-access-key-id',
      secretAccessKey: 'your-secret-access-key',
    });
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Linode">
    ```ts
    import { linode } from '@better-upload/server/clients';

    const s3 = linode({
      region: 'your-linode-region',
      accessKey: 'your-access-key',
      secretKey: 'your-secret-key',
    });
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Custom">
    ```ts
    // for any S3-compatible service
    import { custom } from '@better-upload/server/clients';

    const s3 = custom({
      host: 's3.us-east-1.amazonaws.com',
      accessKeyId: 'your-access-key-id',
      secretAccessKey: 'your-secret-access-key',
      region: 'us-east-1',
      secure: true,
      forcePathStyle: false,
    });
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout>
  You can omit the parameters and let the client get your credentials from
  environment variables.
</Callout>

Objects [#objects]

Helpers for working with objects in S3-compatible storage services. Suggest new helpers by [opening an issue](https://github.com/Nic13Gamer/better-upload/issues).

Presign get object [#presign-get-object]

Generate a pre-signed URL to download an object. Commonly used for client-side downloads.

```ts
import { presignGetObject } from '@better-upload/server/helpers';

const url = await presignGetObject(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
  expiresIn: 3600, // 1 hour
});
```

Get object [#get-object]

Get an object (including its content) from an S3 bucket.

```ts
import { getObjectBlob, getObjectStream } from '@better-upload/server/helpers';

// as a Blob
const objectBlob = await getObjectBlob(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
});

// as a ReadableStream
const objectStream = await getObjectStream(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
});
```

Head object [#head-object]

Get metadata about an object without fetching its content.

```ts
import { headObject } from '@better-upload/server/helpers';

const object = await headObject(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
});
```

List objects V2 [#list-objects-v2]

List objects in an S3 bucket, using the [ListObjectsV2 command](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html).

```ts
import { listObjectsV2 } from '@better-upload/server/helpers';

const { contents } = await listObjectsV2(s3, {
  bucket: 'my-bucket',
});
```

Move object (rename) [#move-object-rename]

Move an object from one key to another, within or between, S3 buckets. Also known as renaming.

```ts
import { moveObject } from '@better-upload/server/helpers';

await moveObject(s3, {
  source: {
    bucket: 'source-bucket',
    key: 'example.png',
  },
  destination: {
    bucket: 'destination-bucket',
    key: 'copy.png',
  },
});
```

<Callout type="warn">
  This copies the object to the new location and then deletes the original
  object. It can be slow.
</Callout>

Copy object [#copy-object]

Copy an object, within or between, S3 buckets.

```ts
import { copyObject } from '@better-upload/server/helpers';

await copyObject(s3, {
  source: {
    bucket: 'source-bucket',
    key: 'example.png',
  },
  destination: {
    bucket: 'destination-bucket',
    key: 'images/example.png',
  },
});
```

Put object [#put-object]

Upload an object to an S3 bucket.

```ts
import { putObject } from '@better-upload/server/helpers';

await putObject(s3, {
  bucket: 'my-bucket',
  key: 'example.txt',
  body: 'Hello, world!',
  contentType: 'text/plain',
});
```

<Callout>
  Do not use this helper for large files or for client-side uploads (use the
  standard router instead).
</Callout>

Delete object [#delete-object]

Delete an object from an S3 bucket.

```ts
import { deleteObject } from '@better-upload/server/helpers';

await deleteObject(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
});
```

Delete objects [#delete-objects]

Delete multiple objects from an S3 bucket in a single request.

```ts
import { deleteObjects } from '@better-upload/server/helpers';

const { deleted, errors } = await deleteObjects(s3, {
  bucket: 'my-bucket',
  objects: [{ key: 'file1.png' }, { key: 'file2.png' }],
});
```

Multipart uploads [#multipart-uploads]

Helpers for working with multipart uploads in S3-compatible storage services.

Create multipart upload [#create-multipart-upload]

Create a new multipart upload in an S3 bucket.

```ts
import { createMultipartUpload } from '@better-upload/server/helpers';

const { uploadId } = await createMultipartUpload(s3, {
  bucket: 'my-bucket',
  key: 'large-file.zip',
  contentType: 'application/zip',
});
```

Upload part [#upload-part]

Upload a part of a multipart upload.

```ts
import { uploadPart } from '@better-upload/server/helpers';

const { eTag } = await uploadPart(s3, {
  bucket: 'my-bucket',
  key: 'large-file.zip',
  uploadId: '...',
  partNumber: 1,
  body: partData,
});
```

Complete multipart upload [#complete-multipart-upload]

Complete a multipart upload in an S3 bucket.

```ts
import { completeMultipartUpload } from '@better-upload/server/helpers';

await completeMultipartUpload(s3, {
  bucket: 'my-bucket',
  key: 'large-file.zip',
  uploadId: '...',
  parts: [
    { partNumber: 1, eTag: '...' },
    { partNumber: 2, eTag: '...' },
    // ...
  ],
});
```

Abort multipart upload [#abort-multipart-upload]

Abort a multipart upload in an S3 bucket.

```ts
import { abortMultipartUpload } from '@better-upload/server/helpers';

await abortMultipartUpload(s3, {
  bucket: 'my-bucket',
  key: 'large-file.zip',
  uploadId: '...',
});
```

Object tagging operations [#object-tagging-operations]

Helpers for managing object tags in S3-compatible storage services.

Get object tagging [#get-object-tagging]

Get the tags of an S3 object.

```ts
import { getObjectTagging } from '@better-upload/server/helpers';

const { tags, tagsObject } = await getObjectTagging(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
});
```

Put object tagging [#put-object-tagging]

Set the tags for an S3 object.

```ts
import { putObjectTagging } from '@better-upload/server/helpers';

await putObjectTagging(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
  tagging: {
    tag1: 'value1',
    tag2: 'value2',
  },
});
```

Delete object tagging [#delete-object-tagging]

Delete all tags from an S3 object.

```ts
import { deleteObjectTagging } from '@better-upload/server/helpers';

await deleteObjectTagging(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
});
```


# Client Hooks (/docs/hooks-multiple)



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.

<PageSelect
  pages="[
  {
    href: '/docs/hooks-multiple',
    title: 'Multiple files',
    description: 'Upload more than one file at once.',
  },
  {
    href: '/docs/hooks-single',
    title: 'Single files',
    description: 'Upload only a single file at once.',
  },
]"
/>

Usage [#usage]

```tsx title="uploader.tsx"
import { useUploadFiles } from '@better-upload/client';

export function Uploader() {
  const {
    upload,
    uploadAsync,
    reset,
    uploadedFiles,
    failedFiles,
    progresses,
    isPending,
    isAborted,
    isSettled,
    isError,
    allSucceeded,
    hasFailedFiles,
    averageProgress,
    error,
    metadata,
    control, // for use in pre-built components
  } = useUploadFiles({
    route: 'images',
  });

  return (
    <input
      type="file"
      multiple
      onChange={(e) => {
        if (e.target.files) {
          upload(e.target.files);
        }
      }}
    />
  );
}
```

<Callout>
  If your upload route handler is not located at `/api/upload`, you need to
  specify the correct path in the `api` option.
</Callout>

Options [#options]

The `useUploadFiles` hook accepts the following options:

<TypeTable
  type="{
  route: {
    description:
      'The route to use for uploading files. Needs to match the upload route in the server.',
    type: 'string',
    required: true,
  },
  api: {
    description: 'The API endpoint to use for uploading files.',
    type: 'string',
    default: '/api/upload',
    required: false,
  },
  uploadBatchSize: {
    description: 'The number of files to upload in parallel.',
    type: 'number',
    default: 'All files at once',
    required: false,
  },
  multipartBatchSize: {
    description:
      'The number of parts that will be uploaded in parallel when uploading a file.',
    type: 'number',
    default: 'All parts at once',
    required: false,
  },
  signal: {
    description: 'Abort signal to cancel the upload.',
    type: 'AbortSignal',
    required: false,
  },
  headers: {
    description:
      'Headers to send to your server when requesting the pre-signed URLs.',
    type: 'HeadersInit',
    typeDescription: 'Can be an object with string keys and values.',
    required: false,
  },
  credentials: {
    description:
      'Credentials mode when requesting pre-signed URLs from your server.',
    type: 'RequestCredentials',
    typeDescription: (
      <>
        Can be <code>include</code>, <code>same-origin</code>, or{' '}
        <code>omit</code>.
      </>
    ),
    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 [#events]

On before upload [#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 [#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 [#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 [#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 [#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 [#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);
  },
});
```

<Callout>
  This event is also called if some input is invalid. For example, if no files
  were selected.
</Callout>

On upload settle [#on-upload-settle]

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

```tsx
useUploadFiles({
  route: 'images',
  onUploadSettle: ({ files, failedFiles, metadata }) => {
    console.log('Upload settled');
  },
});
```

Metadata [#metadata]

It is possible to send metadata from the client to your server on the upload request.

```tsx
export function Uploader() {
  const { upload } = useUploadFiles({
    route: 'images',
  });

  return (
    <input
      type="file"
      multiple
      onChange={(e) => {
        if (e.target.files) {
          upload(e.target.files, {
            // [!code highlight:3]
            metadata: {
              folder: 'my-folder',
            },
          });
        }
      }}
    />
  );
}
```

<Callout>
  You can validate the client metadata on the server by setting the
  `clientMetadataSchema` option in the upload route.
</Callout>


# Client Hooks (/docs/hooks-single)



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.

<PageSelect
  pages="[
  {
    href: '/docs/hooks-multiple',
    title: 'Multiple files',
    description: 'Upload more than one file at once.',
  },
  {
    href: '/docs/hooks-single',
    title: 'Single files',
    description: 'Upload only a single file at once.',
  },
]"
/>

Usage [#usage]

```tsx title="uploader.tsx"
import { useUploadFile } from '@better-upload/client';

export function Uploader() {
  const {
    upload,
    uploadAsync,
    reset,
    uploadedFile,
    progress,
    isPending,
    isAborted,
    isSettled,
    isError,
    isSuccess,
    error,
    metadata,
    control, // for use in pre-built components
  } = useUploadFile({
    route: 'profile',
  });

  return (
    <input
      type="file"
      onChange={(e) => {
        if (e.target.files?.[0]) {
          upload(e.target.files[0]);
        }
      }}
    />
  );
}
```

<Callout>
  If your upload route handler is not located at `/api/upload`, you need to
  specify the correct path in the `api` option.
</Callout>

Options [#options]

The `useUploadFile` hook accepts the following options:

<TypeTable
  type="{
  route: {
    description:
      'The route to use for uploading files. Needs to match the upload route in the server.',
    type: 'string',
    required: true,
  },
  api: {
    description: 'The API endpoint to use for uploading files.',
    type: 'string',
    default: '/api/upload',
    required: false,
  },
  multipartBatchSize: {
    description:
      'The number of parts that will be uploaded in parallel when uploading a file.',
    type: 'number',
    default: 'All parts at once',
    required: false,
  },
  signal: {
    description: 'Abort signal to cancel the upload.',
    type: 'AbortSignal',
    required: false,
  },
  headers: {
    description:
      'Headers to send to your server when requesting the pre-signed URLs.',
    type: 'HeadersInit',
    typeDescription: 'Can be an object with string keys and values.',
    required: false,
  },
  credentials: {
    description:
      'Credentials mode when requesting pre-signed URLs from your server.',
    type: 'RequestCredentials',
    typeDescription: (
      <>
        Can be <code>include</code>, <code>same-origin</code>, or{' '}
        <code>omit</code>.
      </>
    ),
    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 [#events]

On before upload [#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 [#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 [#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 [#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 [#on-error]

Event that is called if the upload fails.

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

<Callout>
  This event is also called if some input is invalid. For example, if no files
  were selected.
</Callout>

On upload settle [#on-upload-settle]

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

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

Metadata [#metadata]

It is possible to send metadata from the client to your server on the upload request.

```tsx
export function Uploader() {
  const { upload } = useUploadFile({
    route: 'profile',
  });

  return (
    <input
      type="file"
      onChange={(e) => {
        if (e.target.files?.[0]) {
          upload(e.target.files[0], {
            // [!code highlight:3]
            metadata: {
              folder: 'my-folder',
            },
          });
        }
      }}
    />
  );
}
```

<Callout>
  You can validate the client metadata on the server by setting the
  `clientMetadataSchema` option in the upload route.
</Callout>


# Introduction (/docs)



Why? [#why]

After needing to implement file uploads from scratch in multiple projects, I realized that there was a need for a better and simpler way to set up file uploads in React while still owning my S3 bucket. I wanted a library that was easy to use, fast to set up, and not bloated with features I didn't need. So I made Better Upload.

Universal [#universal]

Better Upload is framework-agnostic, meaning you can use it with any React framework, like [Next.js](https://nextjs.org), [Remix](https://remix.run), [TanStack Start](https://tanstack.com/start), or any other. It also works with any separate backend server, like [Hono](https://hono.dev), [Elysia](https://elysiajs.com), [Express](https://expressjs.com) and [Fastify](https://fastify.dev).

Developer Experience [#developer-experience]

When creating Better Upload, my main focus was on making the developer experience as smooth as possible.

* **Fast to set up:** It takes only a few minutes to get started and upload files directly to your S3 bucket.
* **Beautiful:** There are copy-and-paste [shadcn/ui](https://ui.shadcn.com) components that you can use to rapidly build your UI.
* **Own your data:** Upload directly to your S3 bucket, so you have full control over files.

LLMs [#llms]

AI agents can access the Better Upload documentation in Markdown by:

* **Full docs:** [`llms-full.txt`](https://better-upload.com/llms-full.txt) - contains the complete documentation in plain Markdown.
* **Per-page content:** Every page in the docs is available as `.mdx`. For example, [`/docs/quickstart.mdx`](https://better-upload.com/docs/quickstart.mdx)


# Quickstart (/docs/quickstart-single)



You can have file uploads in your React app in a few minutes with Better Upload. This guide will walk you through the steps to set it up with any React framework.

Before you start, make sure you have an S3-compatible bucket ready. You can use AWS S3, Cloudflare R2, or any other S3-compatible service.

<PageSelect
  pages="[
  {
    href: '/docs/quickstart',
    title: 'Multiple files',
    description: 'Upload more than one file at once.',
  },
  {
    href: '/docs/quickstart-single',
    title: 'Single files',
    description: 'Upload only a single file at once.',
  },
]"
/>

Uploading your first image [#uploading-your-first-image]

<Steps>
  <Step>
    Install [#install]

    Install the `@better-upload/server` and `@better-upload/client` packages.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm i @better-upload/server @better-upload/client
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add @better-upload/server @better-upload/client
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add @better-upload/server @better-upload/client
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add @better-upload/server @better-upload/client
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Step>

  <Step>
    Set up server [#set-up-server]

    Your server generates pre-signed URLs, which the client uses to upload files directly to the S3 bucket.

    Change `my-bucket` to your bucket name, and [choose your S3 client](/docs/helpers-server#s3-clients).

        <CodeBlockTabs defaultValue="Next.js">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="Next.js">
              Next.js
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="TanStack Start">
              TanStack Start
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="Remix">
              Remix
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="Hono">
              Hono
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="Elysia">
              Elysia
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="Express">
              Express
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="Fastify">
              Fastify
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="Next.js">
            ```ts  title="app/api/upload/route.ts"
            import { route, type Router } from '@better-upload/server';
            import { toRouteHandler } from '@better-upload/server/adapters/next';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                profile: route({
                  fileTypes: ['image/*'],
                }),
              },
            };

            export const { POST } = toRouteHandler(router);
            ```
          </CodeBlockTab>

          <CodeBlockTab value="TanStack Start">
            ```ts  title="routes/api/upload.ts"
            import { createFileRoute } from '@tanstack/react-router';
            import { handleRequest, route, type Router } from '@better-upload/server';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                profile: route({
                  fileTypes: ['image/*'],
                }),
              },
            };

            export const Route = createFileRoute('/api/upload')({
              server: {
                handlers: {
                  POST: async ({ request }) => {
                    return handleRequest(request, router);
                  },
                },
              },
            });
            ```
          </CodeBlockTab>

          <CodeBlockTab value="Remix">
            ```ts  title="app/routes/api.upload.ts"
            import { ActionFunctionArgs } from '@remix-run/node';
            import { handleRequest, route, type Router } from '@better-upload/server';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                profile: route({
                  fileTypes: ['image/*'],
                }),
              },
            };

            export async function action({ request }: ActionFunctionArgs) {
              return handleRequest(request, router);
            }
            ```
          </CodeBlockTab>

          <CodeBlockTab value="Hono">
            ```ts
            // when using a separate backend server, make sure to update the `api` option on the client hooks.

            import { Hono } from 'hono';
            import { handleRequest, route, type Router } from '@better-upload/server';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                profile: route({
                  fileTypes: ['image/*'],
                }),
              },
            };

            const app = new Hono();

            app.post('/upload', (c) => {
              return handleRequest(c.req.raw, router);
            });

            export default app;
            ```
          </CodeBlockTab>

          <CodeBlockTab value="Elysia">
            ```ts
            // when using a separate backend server, make sure to update the `api` option on the client hooks.

            import { Elysia } from 'elysia';
            import { handleRequest, route, type Router } from '@better-upload/server';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                profile: route({
                  fileTypes: ['image/*'],
                }),
              },
            };

            const app = new Elysia()
              .post('/upload', ({ request }) => {
                return handleRequest(request, router);
              })
              .listen(3000);
            ```
          </CodeBlockTab>

          <CodeBlockTab value="Express">
            ```ts
            // when using a separate backend server, make sure to update the `api` option on the client hooks.

            import express from 'express';
            import { route, type Router } from '@better-upload/server';
            import { toNodeHandler } from '@better-upload/server/adapters/node';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                profile: route({
                  fileTypes: ['image/*'],
                }),
              },
            };

            const app = express();

            app.post('/upload', toNodeHandler(router));

            // only mount express json middleware AFTER upload router
            app.use(express.json());

            app.listen(3000);
            ```
          </CodeBlockTab>

          <CodeBlockTab value="Fastify">
            ```ts
            // when using a separate backend server, make sure to update the `api` option on the client hooks.

            import Fastify from 'fastify';
            import { route, type Router } from '@better-upload/server';
            import { toNodeHandler } from '@better-upload/server/adapters/node';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                profile: route({
                  fileTypes: ['image/*'],
                }),
              },
            };

            const app = Fastify();

            app.post('/upload', toNodeHandler(router));

            app.listen({ port: 3000 });
            ```
          </CodeBlockTab>
        </CodeBlockTabs>

    In the example above, we create the upload route `profile`. Learn more about upload routes [here](/docs/routes-single).

        <Accordions>
          <Accordion title="Adding authentication">
            You can run code before uploads in the server. Use the `onBeforeUpload` callback:

            ```ts
            import { RejectUpload, route, type Router } from '@better-upload/server';
            import { aws } from '@better-upload/server/clients';

            const auth = (req: Request) => ({ id: 'fake-user-id' }); // [!code highlight]

            const router: Router = {
              client: aws(),
              bucketName: 'my-bucket',
              routes: {
                profile: route({
                  fileTypes: ['image/*'],
                  // [!code ++:7]
                  onBeforeUpload: async ({ req, file, clientMetadata }) => {
                    const user = await auth(req);

                    if (!user) {
                      throw new RejectUpload('Not logged in!');
                    }
                  },
                }),
              },
            };
            ```
          </Accordion>

          <Accordion title="Modifying S3 object info">
            You can modify the S3 object through the `onBeforeUpload` callback:

            ```ts
            const router: Router = {
              client: aws(),
              bucketName: 'my-bucket',
              routes: {
                profile: route({
                  fileTypes: ['image/*'],
                  // [!code ++:10]
                  onBeforeUpload: async ({ req, file, clientMetadata }) => {
                    return {
                      objectInfo: {
                        key: `files/${file.name}`,
                        metadata: {
                          author: 'user_123',
                        },
                      },
                    };
                  },
                }),
              },
            };
            ```
          </Accordion>

          <Accordion title="Available S3 clients">
            There are built-in clients for popular S3-compatible services. Suggest a new client by [opening an issue](https://github.com/Nic13Gamer/better-upload/issues).

                    <CodeBlockTabs defaultValue="AWS S3">
                      <CodeBlockTabsList>
                        <CodeBlockTabsTrigger value="AWS S3">
                          AWS S3
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="Cloudflare R2">
                          Cloudflare R2
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="Tigris">
                          Tigris
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="Backblaze B2">
                          Backblaze B2
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="DigitalOcean Spaces">
                          DigitalOcean Spaces
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="Wasabi">
                          Wasabi
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="MinIO">
                          MinIO
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="Linode">
                          Linode
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="Custom">
                          Custom
                        </CodeBlockTabsTrigger>
                      </CodeBlockTabsList>

                      <CodeBlockTab value="AWS S3">
                        ```ts
                        import { aws } from '@better-upload/server/clients';

                        const s3 = aws({
                          accessKeyId: 'your-access-key-id',
                          secretAccessKey: 'your-secret-access-key',
                          region: 'us-east-1',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="Cloudflare R2">
                        ```ts
                        import { cloudflare } from '@better-upload/server/clients';

                        const s3 = cloudflare({
                          accountId: 'your-account-id',
                          accessKeyId: 'your-access-key-id',
                          secretAccessKey: 'your-secret-access-key',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="Tigris">
                        ```ts
                        import { tigris } from '@better-upload/server/clients';

                        const s3 = tigris({
                          accessKeyId: 'your-access-key-id',
                          secretAccessKey: 'your-secret-access-key',
                          endpoint: '...', // optional
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="Backblaze B2">
                        ```ts
                        import { backblaze } from '@better-upload/server/clients';

                        const s3 = backblaze({
                          region: 'your-backblaze-region',
                          applicationKeyId: 'your-application-key-id',
                          applicationKey: 'your-application-key',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="DigitalOcean Spaces">
                        ```ts
                        import { digitalOcean } from '@better-upload/server/clients';

                        const s3 = digitalOcean({
                          region: 'your-spaces-region',
                          key: 'your-spaces-key',
                          secret: 'your-spaces-secret',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="Wasabi">
                        ```ts
                        import { wasabi } from '@better-upload/server/clients';

                        const s3 = wasabi({
                          region: 'your-wasabi-region',
                          accessKeyId: 'your-access-key-id',
                          secretAccessKey: 'your-secret-access-key',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="MinIO">
                        ```ts
                        import { minio } from '@better-upload/server/clients';

                        const s3 = minio({
                          region: 'your-minio-region',
                          endpoint: 'https://minio.example.com',
                          accessKeyId: 'your-access-key-id',
                          secretAccessKey: 'your-secret-access-key',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="Linode">
                        ```ts
                        import { linode } from '@better-upload/server/clients';

                        const s3 = linode({
                          region: 'your-linode-region',
                          accessKey: 'your-access-key',
                          secretKey: 'your-secret-key',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="Custom">
                        ```ts
                        // for any S3-compatible service
                        import { custom } from '@better-upload/server/clients';

                        const s3 = custom({
                          host: 's3.us-east-1.amazonaws.com',
                          accessKeyId: 'your-access-key-id',
                          secretAccessKey: 'your-secret-access-key',
                          region: 'us-east-1',
                          secure: true,
                          forcePathStyle: false,
                        });
                        ```
                      </CodeBlockTab>
                    </CodeBlockTabs>
          </Accordion>
        </Accordions>
  </Step>

  <Step>
    Create `<Uploader />` component [#create-uploader--component]

    We will now build our UI using pre-built components. We'll use `<UploadButton />` for single file uploads.

    Install it via the [shadcn](https://ui.shadcn.com/) CLI:

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @better-upload/upload-button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @better-upload/upload-button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @better-upload/upload-button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @better-upload/upload-button
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    We'll also use the `useUploadFile` hook. The complete code looks like this:

    ```tsx title="uploader.tsx"
    'use client'; // only for Next.js

    import { useUploadFile } from '@better-upload/client';
    import { UploadButton } from '@/components/ui/upload-button';

    export function Uploader() {
      const { control } = useUploadFile({
        route: 'profile',
      });

      return <UploadButton control={control} accept="image/*" />;
    }
    ```

    Learn more about the hooks [here](/docs/hooks-single).
  </Step>

  <Step>
    Place the component [#place-the-component]

    Now place the `<Uploader />` component in your app.

    ```tsx title="page.tsx"
    import { Uploader } from '@/components/uploader';

    export default function Page() {
      return (
        <main className="flex min-h-screen flex-col items-center justify-center">
          <Uploader />
        </main>
      );
    }
    ```
  </Step>

  <Step>
    You're done! 🎉 [#youre-done-]

    You can now run your app and upload images directly to any S3-compatible service!

    If you plan on uploading files larger than **5GB**, take a look at [multipart uploads](/docs/routes-single#multipart-uploads).

    <Accordions>
      <Accordion title="CORS Configuration">
        Make sure to also correctly configure CORS on your bucket. Here is an example:

        ```json
        [
          {
            "AllowedOrigins": [
              "http://localhost:3000",
              "https://example.com" // Add your domain here
            ],
            "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
            "AllowedHeaders": ["*"],
            "ExposeHeaders": ["ETag"]
          }
        ]
        ```

        Learn more about CORS [here](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html).
      </Accordion>
    </Accordions>
  </Step>
</Steps>

Learn more [#learn-more]

Concepts [#concepts]

<Cards>
  <Card href="/docs/routes-single" title="Upload routes" description="Configure upload routes for different behaviors." />

  <Card href="/docs/hooks-single" title="Client hooks" description="Use client-side hooks to easily upload files." />
</Cards>

Guides [#guides]

<Cards>
  <Card href="/docs/guides/forms/react-hook-form" title="React Hook Form" description="Add file uploads to forms built with React Hook Form." />

  <Card href="/docs/guides/forms/tanstack-form" title="TanStack Form" description="Add file uploads to forms built with TanStack Form." />

  <Card href="/docs/guides/tanstack-query" title="TanStack Query" description="Use TanStack Query to manage the upload process." />
</Cards>

Components [#components]

<Cards>
  <Card href="/docs/components/upload-button" title="Upload button" description="A button that uploads a single file." />

  <Card href="/docs/components/upload-dropzone" title="Upload dropzone" description="A dropzone that uploads multiple files." />

  <Card href="/docs/components/upload-progress" title="Upload progress" description="A component to display upload progress for files being uploaded." />

  <Card href="/docs/components/paste-upload-area" title="Paste upload area" description="A wrapper component that enables file uploads via paste events." />
</Cards>


# Quickstart (/docs/quickstart)



You can have file uploads in your React app in a few minutes with Better Upload. This guide will walk you through the steps to set it up with any React framework.

Before you start, make sure you have an S3-compatible bucket ready. You can use AWS S3, Cloudflare R2, or any other S3-compatible service.

<PageSelect
  pages="[
  {
    href: '/docs/quickstart',
    title: 'Multiple files',
    description: 'Upload more than one file at once.',
  },
  {
    href: '/docs/quickstart-single',
    title: 'Single files',
    description: 'Upload only a single file at once.',
  },
]"
/>

Uploading images [#uploading-images]

<Steps>
  <Step>
    Install [#install]

    Install the `@better-upload/server` and `@better-upload/client` packages.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm i @better-upload/server @better-upload/client
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add @better-upload/server @better-upload/client
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add @better-upload/server @better-upload/client
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add @better-upload/server @better-upload/client
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Step>

  <Step>
    Set up server [#set-up-server]

    Your server generates pre-signed URLs, which the client uses to upload files directly to the S3 bucket.

    Change `my-bucket` to your bucket name, and [choose your S3 client](/docs/helpers-server#s3-clients).

        <CodeBlockTabs defaultValue="Next.js">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="Next.js">
              Next.js
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="TanStack Start">
              TanStack Start
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="Remix">
              Remix
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="Hono">
              Hono
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="Elysia">
              Elysia
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="Express">
              Express
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="Fastify">
              Fastify
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="Next.js">
            ```ts  title="app/api/upload/route.ts"
            import { route, type Router } from '@better-upload/server';
            import { toRouteHandler } from '@better-upload/server/adapters/next';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                images: route({
                  fileTypes: ['image/*'],
                  multipleFiles: true,
                  maxFiles: 4,
                }),
              },
            };

            export const { POST } = toRouteHandler(router);
            ```
          </CodeBlockTab>

          <CodeBlockTab value="TanStack Start">
            ```ts  title="routes/api/upload.ts"
            import { createFileRoute } from '@tanstack/react-router';
            import { handleRequest, route, type Router } from '@better-upload/server';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                images: route({
                  fileTypes: ['image/*'],
                  multipleFiles: true,
                  maxFiles: 4,
                }),
              },
            };

            export const Route = createFileRoute('/api/upload')({
              server: {
                handlers: {
                  POST: async ({ request }) => {
                    return handleRequest(request, router);
                  },
                },
              },
            });
            ```
          </CodeBlockTab>

          <CodeBlockTab value="Remix">
            ```ts  title="app/routes/api.upload.ts"
            import { ActionFunctionArgs } from '@remix-run/node';
            import { handleRequest, route, type Router } from '@better-upload/server';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                images: route({
                  fileTypes: ['image/*'],
                  multipleFiles: true,
                  maxFiles: 4,
                }),
              },
            };

            export async function action({ request }: ActionFunctionArgs) {
              return handleRequest(request, router);
            }
            ```
          </CodeBlockTab>

          <CodeBlockTab value="Hono">
            ```ts
            // when using a separate backend server, make sure to update the `api` option on the client hooks.

            import { Hono } from 'hono';
            import { handleRequest, route, type Router } from '@better-upload/server';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                images: route({
                  fileTypes: ['image/*'],
                  multipleFiles: true,
                  maxFiles: 4,
                }),
              },
            };

            const app = new Hono();

            app.post('/upload', (c) => {
              return handleRequest(c.req.raw, router);
            });

            export default app;
            ```
          </CodeBlockTab>

          <CodeBlockTab value="Elysia">
            ```ts
            // when using a separate backend server, make sure to update the `api` option on the client hooks.

            import { Elysia } from 'elysia';
            import { handleRequest, route, type Router } from '@better-upload/server';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                images: route({
                  fileTypes: ['image/*'],
                  multipleFiles: true,
                  maxFiles: 4,
                }),
              },
            };

            const app = new Elysia()
              .post('/upload', ({ request }) => {
                return handleRequest(request, router);
              })
              .listen(3000);
            ```
          </CodeBlockTab>

          <CodeBlockTab value="Express">
            ```ts
            // when using a separate backend server, make sure to update the `api` option on the client hooks.

            import express from 'express';
            import { route, type Router } from '@better-upload/server';
            import { toNodeHandler } from '@better-upload/server/adapters/node';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                images: route({
                  fileTypes: ['image/*'],
                  multipleFiles: true,
                  maxFiles: 4,
                }),
              },
            };

            const app = express();

            app.post('/upload', toNodeHandler(router));

            // only mount express json middleware AFTER upload router
            app.use(express.json());

            app.listen(3000);
            ```
          </CodeBlockTab>

          <CodeBlockTab value="Fastify">
            ```ts
            // when using a separate backend server, make sure to update the `api` option on the client hooks.

            import Fastify from 'fastify';
            import { route, type Router } from '@better-upload/server';
            import { toNodeHandler } from '@better-upload/server/adapters/node';
            import { aws } from '@better-upload/server/clients';

            const router: Router = {
              client: aws(), // or cloudflare(), backblaze(), tigris(), ... // [!code highlight]
              bucketName: 'my-bucket', // [!code highlight]
              routes: {
                images: route({
                  fileTypes: ['image/*'],
                  multipleFiles: true,
                  maxFiles: 4,
                }),
              },
            };

            const app = Fastify();

            app.post('/upload', toNodeHandler(router));

            app.listen({ port: 3000 });
            ```
          </CodeBlockTab>
        </CodeBlockTabs>

    In the example above, we create the upload route `images`. Learn more about upload routes [here](/docs/routes-multiple).

        <Accordions>
          <Accordion title="Adding authentication">
            You can run code before uploads in the server. Use the `onBeforeUpload` callback:

            ```ts
            import { RejectUpload, route, type Router } from '@better-upload/server';
            import { aws } from '@better-upload/server/clients';

            const auth = (req: Request) => ({ id: 'fake-user-id' }); // [!code highlight]

            const router: Router = {
              client: aws(),
              bucketName: 'my-bucket',
              routes: {
                images: route({
                  fileTypes: ['image/*'],
                  multipleFiles: true,
                  maxFiles: 4,
                  // [!code ++:7]
                  onBeforeUpload: async ({ req, files, clientMetadata }) => {
                    const user = await auth(req);

                    if (!user) {
                      throw new RejectUpload('Not logged in!');
                    }
                  },
                }),
              },
            };
            ```
          </Accordion>

          <Accordion title="Modifying S3 object info">
            You can modify the S3 object through the `onBeforeUpload` callback:

            ```ts
            const router: Router = {
              client: aws(),
              bucketName: 'my-bucket',
              routes: {
                images: route({
                  fileTypes: ['image/*'],
                  multipleFiles: true,
                  maxFiles: 4,
                  // [!code ++:10]
                  onBeforeUpload: async ({ req, files, clientMetadata }) => {
                    return {
                      generateObjectInfo: ({ file }) => ({
                        key: `files/${file.name}`,
                        metadata: {
                          author: 'user_123',
                        },
                      }),
                    };
                  },
                }),
              },
            };
            ```
          </Accordion>

          <Accordion title="Available S3 clients">
            There are built-in clients for popular S3-compatible services. Suggest a new client by [opening an issue](https://github.com/Nic13Gamer/better-upload/issues).

                    <CodeBlockTabs defaultValue="AWS S3">
                      <CodeBlockTabsList>
                        <CodeBlockTabsTrigger value="AWS S3">
                          AWS S3
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="Cloudflare R2">
                          Cloudflare R2
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="Tigris">
                          Tigris
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="Backblaze B2">
                          Backblaze B2
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="DigitalOcean Spaces">
                          DigitalOcean Spaces
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="Wasabi">
                          Wasabi
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="MinIO">
                          MinIO
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="Linode">
                          Linode
                        </CodeBlockTabsTrigger>

                        <CodeBlockTabsTrigger value="Custom">
                          Custom
                        </CodeBlockTabsTrigger>
                      </CodeBlockTabsList>

                      <CodeBlockTab value="AWS S3">
                        ```ts
                        import { aws } from '@better-upload/server/clients';

                        const s3 = aws({
                          accessKeyId: 'your-access-key-id',
                          secretAccessKey: 'your-secret-access-key',
                          region: 'us-east-1',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="Cloudflare R2">
                        ```ts
                        import { cloudflare } from '@better-upload/server/clients';

                        const s3 = cloudflare({
                          accountId: 'your-account-id',
                          accessKeyId: 'your-access-key-id',
                          secretAccessKey: 'your-secret-access-key',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="Tigris">
                        ```ts
                        import { tigris } from '@better-upload/server/clients';

                        const s3 = tigris({
                          accessKeyId: 'your-access-key-id',
                          secretAccessKey: 'your-secret-access-key',
                          endpoint: '...', // optional
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="Backblaze B2">
                        ```ts
                        import { backblaze } from '@better-upload/server/clients';

                        const s3 = backblaze({
                          region: 'your-backblaze-region',
                          applicationKeyId: 'your-application-key-id',
                          applicationKey: 'your-application-key',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="DigitalOcean Spaces">
                        ```ts
                        import { digitalOcean } from '@better-upload/server/clients';

                        const s3 = digitalOcean({
                          region: 'your-spaces-region',
                          key: 'your-spaces-key',
                          secret: 'your-spaces-secret',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="Wasabi">
                        ```ts
                        import { wasabi } from '@better-upload/server/clients';

                        const s3 = wasabi({
                          region: 'your-wasabi-region',
                          accessKeyId: 'your-access-key-id',
                          secretAccessKey: 'your-secret-access-key',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="MinIO">
                        ```ts
                        import { minio } from '@better-upload/server/clients';

                        const s3 = minio({
                          region: 'your-minio-region',
                          endpoint: 'https://minio.example.com',
                          accessKeyId: 'your-access-key-id',
                          secretAccessKey: 'your-secret-access-key',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="Linode">
                        ```ts
                        import { linode } from '@better-upload/server/clients';

                        const s3 = linode({
                          region: 'your-linode-region',
                          accessKey: 'your-access-key',
                          secretKey: 'your-secret-key',
                        });
                        ```
                      </CodeBlockTab>

                      <CodeBlockTab value="Custom">
                        ```ts
                        // for any S3-compatible service
                        import { custom } from '@better-upload/server/clients';

                        const s3 = custom({
                          host: 's3.us-east-1.amazonaws.com',
                          accessKeyId: 'your-access-key-id',
                          secretAccessKey: 'your-secret-access-key',
                          region: 'us-east-1',
                          secure: true,
                          forcePathStyle: false,
                        });
                        ```
                      </CodeBlockTab>
                    </CodeBlockTabs>
          </Accordion>
        </Accordions>
  </Step>

  <Step>
    Create `<Uploader />` component [#create-uploader--component]

    We will now build our UI using pre-built components. Use `<UploadDropzone />` for multiple file uploads.

    Install it via the [shadcn](https://ui.shadcn.com/) CLI:

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @better-upload/upload-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @better-upload/upload-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @better-upload/upload-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @better-upload/upload-dropzone
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    We'll also use the `useUploadFiles` hook. The complete code looks like this:

    ```tsx title="uploader.tsx"
    'use client'; // only for Next.js

    import { useUploadFiles } from '@better-upload/client';
    import { UploadDropzone } from '@/components/ui/upload-dropzone';

    export function Uploader() {
      const { control } = useUploadFiles({
        route: 'images',
      });

      return (
        <UploadDropzone
          control={control}
          accept="image/*"
          description={{
            maxFiles: 4,
            maxFileSize: '5MB',
            fileTypes: 'JPEG, PNG, GIF',
          }}
        />
      );
    }
    ```

    Learn more about the hooks [here](/docs/hooks-multiple).
  </Step>

  <Step>
    Place the component [#place-the-component]

    Now place the `<Uploader />` component in your app.

    ```tsx title="page.tsx"
    import { Uploader } from '@/components/uploader';

    export default function Page() {
      return (
        <main className="flex min-h-screen flex-col items-center justify-center">
          <Uploader />
        </main>
      );
    }
    ```
  </Step>

  <Step>
    You're done! 🎉 [#youre-done-]

    You can now run your app and upload images directly to any S3-compatible service!

    If you plan on uploading files larger than **5GB**, take a look at [multipart uploads](/docs/routes-multiple#multipart-uploads).

    <Accordions>
      <Accordion title="CORS Configuration">
        Make sure to also correctly configure CORS on your bucket. Here is an example:

        ```json
        [
          {
            "AllowedOrigins": [
              "http://localhost:3000",
              "https://example.com" // Add your domain here
            ],
            "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
            "AllowedHeaders": ["*"],
            "ExposeHeaders": ["ETag"]
          }
        ]
        ```

        Learn more about CORS [here](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html).
      </Accordion>
    </Accordions>
  </Step>
</Steps>

Learn more [#learn-more]

Concepts [#concepts]

<Cards>
  <Card href="/docs/routes-multiple" title="Upload routes" description="Configure upload routes for different behaviors." />

  <Card href="/docs/hooks-multiple" title="Client hooks" description="Use client-side hooks to easily upload files." />
</Cards>

Guides [#guides]

<Cards>
  <Card href="/docs/guides/forms/react-hook-form" title="React Hook Form" description="Add file uploads to forms built with React Hook Form." />

  <Card href="/docs/guides/forms/tanstack-form" title="TanStack Form" description="Add file uploads to forms built with TanStack Form." />

  <Card href="/docs/guides/tanstack-query" title="TanStack Query" description="Use TanStack Query to manage the upload process." />
</Cards>

Components [#components]

<Cards>
  <Card href="/docs/components/upload-button" title="Upload button" description="A button that uploads a single file." />

  <Card href="/docs/components/upload-dropzone" title="Upload dropzone" description="A dropzone that uploads multiple files." />

  <Card href="/docs/components/upload-progress" title="Upload progress" description="A component to display upload progress for files being uploaded." />

  <Card href="/docs/components/paste-upload-area" title="Paste upload area" description="A wrapper component that enables file uploads via paste events." />
</Cards>


# Upload Routes (/docs/routes-multiple)



Upload routes are where you define how files are uploaded. To define a route, use the `route` function.

You can create multiple routes for different purposes (e.g. images, videos).

<PageSelect
  pages="[
  {
    href: '/docs/routes-multiple',
    title: 'Multiple files',
    description: 'Upload more than one file at once.',
  },
  {
    href: '/docs/routes-single',
    title: 'Single files',
    description: 'Upload only a single file at once.',
  },
]"
/>

Here is a basic example of a multiple file upload route:

```ts
import { route } from '@better-upload/server';

route({
  multipleFiles: true,
  fileTypes: ['image/*'], // Accepts all image types
  maxFileSize: 1024 * 1024 * 4, // 4MB
});
```

Multiple file routes have the following options:

<TypeTable
  type="{
  maxFiles: {
    description: 'The maximum number of files that can be uploaded at once.',
    type: 'number',
    default: 3,
    required: false,
  },
  fileTypes: {
    description: (
      <>
        An array of file types to accept. Use any valid MIME type. You can use
        wildcards like <code>image/*</code>.
      </>
    ),
    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 [#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 [#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',
    };
  },
});
```

<Callout title="Rejecting uploads">
  Throw `RejectUpload` to reject the file upload. This will also send the error
  message to the client.
</Callout>

You can return an object with the following properties:

<TypeTable
  type="{
  generateObjectInfo: {
    description: (
      <>
        Information about the S3 object. Includes the object key, metadata,
        ACL, and other properties.
        <br/>
        <br/>
        You can also skip the upload of specific files by using <code>skip</code>.
      </>
    ),
    type: '() => object',
    typeDescription: (
      <>
        Can return: <code>key</code>, <code>metadata</code>, <code>acl</code>,{' '}
        <code>storageClass</code>, <code>cacheControl</code>, <code>tagging</code>,{' '}
        <code>skip</code>.
      </>
    ),
    required: false,
  },
  metadata: {
    description: (
      <>
        Metadata to be passed to the <code>onAfterSignedUrl</code> 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 [#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:

<TypeTable
  type="{
  metadata: {
    description:
      'Metadata to be sent back to the client. Needs to be JSON serializable.',
    type: 'object',
    required: false,
  },
}"
/>

Multipart uploads [#multipart-uploads]

If you want to upload files larger than **5GB**, you must use multipart uploads. To enable it, set `multipart` to `true`. It works both for single and multiple files. No change is needed in the client.

```ts
route({
  multipleFiles: true,
  multipart: true, // [!code highlight]
  partSize: 1024 * 1024 * 20, // 20MB, default is 50MB [!code highlight]
});
```

You can now also modify the following options:

<TypeTable
  type="{
  partSize: {
    description: 'The size of each part in bytes.',
    type: 'number',
    default: '52428800 (50MB)',
    required: false,
  },
  partSignedUrlExpiresIn: {
    description: 'The time in seconds the part pre-signed URL is valid.',
    type: 'number',
    default: '1500 (25 minutes)',
    required: false,
  },
  completeSignedUrlExpiresIn: {
    description: 'The time in seconds the complete pre-signed URL is valid.',
    type: 'number',
    default: '1800 (30 minutes)',
    required: false,
  },
}"
/>

<Callout>
  Even for files under 5GB, using multipart uploads can speed up the upload
  process. Empty files (0 bytes) will fail to upload with multipart uploads.
</Callout>

Router [#router]

The router is where all upload routes are defined. To define a router, create an object with the `Router` type.

```ts
import { type Router } from '@better-upload/server';

export const router: Router = {
  client: s3,
  bucketName: 'my-bucket',
  routes: {
    // your routes...
  },
};
```


# Upload Routes (/docs/routes-single)



Upload routes are where you define how files are uploaded. To define a route, use the `route` function.

You can create multiple routes for different purposes (e.g. images, videos).

<PageSelect
  pages="[
  {
    href: '/docs/routes-multiple',
    title: 'Multiple files',
    description: 'Upload more than one file at once.',
  },
  {
    href: '/docs/routes-single',
    title: 'Single files',
    description: 'Upload only a single file at once.',
  },
]"
/>

Here is a basic example of a single file upload route:

```ts
import { route } from '@better-upload/server';

route({
  fileTypes: ['image/*'], // Accepts all image types
  maxFileSize: 1024 * 1024 * 4, // 4MB
});
```

Single file routes have the following options:

<TypeTable
  type="{
  fileTypes: {
    description: (
      <>
        An array of file types to accept. Use any valid MIME type. You can use
        wildcards like <code>image/*</code>.
      </>
    ),
    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 [#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 [#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',
    };
  },
});
```

<Callout title="Rejecting uploads">
  Throw `RejectUpload` to reject the file upload. This will also send the error
  message to the client.
</Callout>

You can return an object with the following properties:

<TypeTable
  type="{
  objectInfo: {
    description:
      'Information about the S3 object. Includes the object key, metadata, ACL, and other properties.',
    type: 'object',
    typeDescription: (
      <>
        Can return: <code>key</code>, <code>metadata</code>, <code>acl</code>,{' '}
        <code>storageClass</code>, <code>cacheControl</code>, <code>tagging</code>.
      </>
    ),
    required: false,
  },
  metadata: {
    description: (
      <>
        Metadata to be passed to the <code>onAfterSignedUrl</code> 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 [#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:

<TypeTable
  type="{
  metadata: {
    description:
      'Metadata to be sent back to the client. Needs to be JSON serializable.',
    type: 'object',
    required: false,
  },
}"
/>

Multipart uploads [#multipart-uploads]

If you want to upload files larger than **5GB**, you must use multipart uploads. To enable it, set `multipart` to `true`. It works both for single and multiple files. No change is needed in the client.

```ts
route({
  multipleFiles: true,
  multipart: true, // [!code highlight]
  partSize: 1024 * 1024 * 20, // 20MB, default is 50MB [!code highlight]
});
```

You can now also modify the following options:

<TypeTable
  type="{
  partSize: {
    description: 'The size of each part in bytes.',
    type: 'number',
    default: '52428800 (50MB)',
    required: false,
  },
  partSignedUrlExpiresIn: {
    description: 'The time in seconds the part pre-signed URL is valid.',
    type: 'number',
    default: '1500 (25 minutes)',
    required: false,
  },
  completeSignedUrlExpiresIn: {
    description: 'The time in seconds the complete pre-signed URL is valid.',
    type: 'number',
    default: '1800 (30 minutes)',
    required: false,
  },
}"
/>

<Callout>
  Even for files under 5GB, using multipart uploads can speed up the upload
  process. Empty files (0 bytes) will fail to upload with multipart uploads.
</Callout>

Router [#router]

The router is where all upload routes are defined. To define a router, create an object with the `Router` type.

```ts
import { type Router } from '@better-upload/server';

export const router: Router = {
  client: s3,
  bucketName: 'my-bucket',
  routes: {
    // your routes...
  },
};
```


# Paste Upload Area (/docs/components/paste-upload-area)





Preview [#preview]

<Showcase>
  <PasteUploadAreaDemo />
</Showcase>

Installation [#installation]

<Tabs items="['CLI', 'Manual']">
  <Tab value="CLI">
    ```bash
    npx shadcn@latest add @better-upload/paste-upload-area
    ```
  </Tab>

  <Tab value="Manual">
    <Steps>
      <Step>
        **Copy and paste the following code into your project.**

        ```tsx title='components/ui/paste-upload-area.tsx'
        import type { UploadHookControl } from '@better-upload/client';

        type PasteUploadAreaProps = {
          children: React.ReactNode;
          control: UploadHookControl<true>;
          metadata?: Record<string, unknown>;
          uploadOverride?: (
            ...args: Parameters<UploadHookControl<true>['upload']>
          ) => void;

          // Add any additional props you need.
        };

        export function PasteUploadArea({
          children,
          control: { upload, isPending },
          metadata,
          uploadOverride,
        }: PasteUploadAreaProps) {
          return (
            <div
              onPasteCapture={(e) => {
                const files = e.clipboardData.files;
                if (files.length > 0 && !isPending) {
                  if (uploadOverride) {
                    uploadOverride(files, { metadata });
                  } else {
                    upload(files, { metadata });
                  }
                }
              }}
            >
              {children}
            </div>
          );
        }

        ```
      </Step>

      <Step>
        **Update the import paths to match your project setup.**
      </Step>
    </Steps>
  </Tab>
</Tabs>

Usage [#usage]

The `<PasteUploadArea />` component should be used with the `useUploadFiles` hook.

```tsx
'use client';

import { useUploadFiles } from '@better-upload/client';
import { PasteUploadArea } from '@/components/ui/paste-upload-area';

export function Uploader() {
  const { control, isPending } = useUploadFiles({
    route: 'images',
  });

  return (
    <PasteUploadArea control={control}>
      <input placeholder="Paste to upload" disabled={isPending} />
    </PasteUploadArea>
  );
}
```

Files pasted within any child element of the component will be uploaded to the desired route.

Props [#props]

<TypeTable
  type="{
  control: {
    type: 'object',
    description: 'Control object returned by the useUploadFiles hook.',
    required: true,
  },
  metadata: {
    type: 'Record<string, unknown>',
    description:
      'Metadata to send to your server on upload. Needs to be JSON serializable.',
  },
  uploadOverride: {
    type: 'function',
    description:
      'Override the default upload function. For example, set files in an array, and upload them after form submission.',
  },
}"
/>


# Upload Button (/docs/components/upload-button)





Preview [#preview]

<Showcase>
  <UploadButtonDemo />
</Showcase>

Installation [#installation]

<Tabs items="['CLI', 'Manual']">
  <Tab value="CLI">
    ```bash
    npx shadcn@latest add @better-upload/upload-button
    ```
  </Tab>

  <Tab value="Manual">
    <Steps>
      <Step>
        **Install the following dependencies:**

        <CodeBlockTabs defaultValue="npm" groupId="package-manager">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npm i lucide-react
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm add lucide-react
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn add lucide-react
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun add lucide-react
            ```
          </CodeBlockTab>
        </CodeBlockTabs>

        Also add the [shadcn/ui button](https://ui.shadcn.com/docs/components/button) component to your project. As the upload button is built on top of it.
      </Step>

      <Step>
        **Copy and paste the following code into your project.**

        ```tsx title='components/ui/upload-button.tsx'
        import { Button } from '@/components/ui/button';
        import type { UploadHookControl } from '@better-upload/client';
        import { Loader2, Upload } from 'lucide-react';
        import { useId } from 'react';

        type UploadButtonProps = {
          control: UploadHookControl<false>;
          id?: string;
          accept?: string;
          metadata?: Record<string, unknown>;
          uploadOverride?: (
            ...args: Parameters<UploadHookControl<false>['upload']>
          ) => void;

          // Add any additional props you need.
        };

        export function UploadButton({
          control: { upload, isPending },
          id: _id,
          accept,
          metadata,
          uploadOverride,
        }: UploadButtonProps) {
          const id = useId();

          return (
            <Button disabled={isPending} className="relative" type="button">
              <label htmlFor={_id || id} className="absolute inset-0 cursor-pointer">
                <input
                  id={_id || id}
                  disabled={isPending}
                  className="absolute inset-0 size-0 opacity-0"
                  type="file"
                  accept={accept}
                  onChange={(e) => {
                    if (e.target.files?.[0] && !isPending) {
                      if (uploadOverride) {
                        uploadOverride(e.target.files[0], { metadata });
                      } else {
                        upload(e.target.files[0], { metadata });
                      }
                    }
                    e.target.value = '';
                  }}
                />
              </label>
              {isPending ? (
                <>
                  <Loader2 className="size-4 animate-spin" />
                  Upload file
                </>
              ) : (
                <>
                  <Upload className="size-4" />
                  Upload file
                </>
              )}
            </Button>
          );
        }

        ```
      </Step>

      <Step>
        **Update the import paths to match your project setup.**
      </Step>
    </Steps>
  </Tab>
</Tabs>

Usage [#usage]

The `<UploadButton />` component should be used with the `useUploadFile` hook.

```tsx
'use client';

import { useUploadFile } from '@better-upload/client';
import { UploadButton } from '@/components/ui/upload-button';

export function Uploader() {
  const { control } = useUploadFile({
    route: 'profile',
  });

  return <UploadButton control={control} accept="image/*" />;
}
```

The button will open a file picker dialog when clicked, and upload the selected file to the desired route.

Props [#props]

<TypeTable
  type="{
  control: {
    type: 'object',
    description: 'Control object returned by the useUploadFile hook.',
    required: true,
  },
  id: {
    type: 'string',
    description: 'The id of the input element.',
  },
  accept: {
    type: 'string',
    description: 'The file types that the input should accept.',
  },
  metadata: {
    type: 'Record<string, unknown>',
    description:
      'Metadata to send to your server on upload. Needs to be JSON serializable.',
  },
  uploadOverride: {
    type: 'function',
    description:
      'Override the default upload function. For example, set files in an array, and upload them after form submission.',
  },
}"
/>


# Upload Dropzone (/docs/components/upload-dropzone)





Preview [#preview]

<Showcase>
  <UploadDropzoneDemo />
</Showcase>

Installation [#installation]

<Tabs items="['CLI', 'Manual']">
  <Tab value="CLI">
    ```bash
    npx shadcn@latest add @better-upload/upload-dropzone
    ```
  </Tab>

  <Tab value="Manual">
    <Steps>
      <Step>
        **Install the following dependencies:**

        <CodeBlockTabs defaultValue="npm" groupId="package-manager">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npm i lucide-react react-dropzone
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm add lucide-react react-dropzone
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn add lucide-react react-dropzone
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun add lucide-react react-dropzone
            ```
          </CodeBlockTab>
        </CodeBlockTabs>

        Make sure to have [shadcn/ui](https://ui.shadcn.com/docs/installation) set up in your project.
      </Step>

      <Step>
        **Copy and paste the following code into your project.**

        ```tsx title='components/ui/upload-dropzone.tsx'
        import { cn } from '@/lib/utils';
        import type { UploadHookControl } from '@better-upload/client';
        import { Loader2, Upload } from 'lucide-react';
        import { useId } from 'react';
        import { useDropzone } from 'react-dropzone';

        type UploadDropzoneProps = {
          control: UploadHookControl<true>;
          id?: string;
          accept?: string;
          metadata?: Record<string, unknown>;
          description?:
            | {
                fileTypes?: string;
                maxFileSize?: string;
                maxFiles?: number;
              }
            | string;
          uploadOverride?: (
            ...args: Parameters<UploadHookControl<true>['upload']>
          ) => void;

          // Add any additional props you need.
        };

        export function UploadDropzone({
          control: { upload, isPending },
          id: _id,
          accept,
          metadata,
          description,
          uploadOverride,
        }: UploadDropzoneProps) {
          const id = useId();

          const { getRootProps, getInputProps, isDragActive, inputRef } = useDropzone({
            onDrop: (files) => {
              if (files.length > 0 && !isPending) {
                if (uploadOverride) {
                  uploadOverride(files, { metadata });
                } else {
                  upload(files, { metadata });
                }
              }
              inputRef.current.value = '';
            },
            noClick: true,
          });

          return (
            <div
              className={cn(
                'border-input text-foreground relative rounded-lg border border-dashed transition-colors',
                {
                  'border-primary/80': isDragActive,
                }
              )}
            >
              <label
                {...getRootProps()}
                className={cn(
                  'dark:bg-input/10 flex w-full min-w-72 cursor-pointer flex-col items-center justify-center rounded-lg bg-transparent px-2 py-6 transition-colors',
                  {
                    'text-muted-foreground cursor-not-allowed': isPending,
                    'hover:bg-accent dark:hover:bg-accent/40': !isPending,
                    'opacity-0': isDragActive,
                  }
                )}
                htmlFor={_id || id}
              >
                <div className="my-2">
                  {isPending ? (
                    <Loader2 className="size-6 animate-spin" />
                  ) : (
                    <Upload className="size-6" />
                  )}
                </div>

                <div className="mt-3 space-y-1 text-center">
                  <p className="text-sm font-semibold">Drag and drop files here</p>

                  <p className="text-muted-foreground max-w-64 text-xs">
                    {typeof description === 'string' ? (
                      description
                    ) : (
                      <>
                        {description?.maxFiles &&
                          `You can upload ${description.maxFiles} file${description.maxFiles !== 1 ? 's' : ''}.`}{' '}
                        {description?.maxFileSize &&
                          `${description.maxFiles !== 1 ? 'Each u' : 'U'}p to ${description.maxFileSize}.`}{' '}
                        {description?.fileTypes && `Accepted ${description.fileTypes}.`}
                      </>
                    )}
                  </p>
                </div>

                <input
                  {...getInputProps()}
                  type="file"
                  multiple
                  id={_id || id}
                  accept={accept}
                  disabled={isPending}
                />
              </label>

              {isDragActive && (
                <div className="pointer-events-none absolute inset-0 rounded-lg">
                  <div className="dark:bg-accent/40 bg-accent flex size-full flex-col items-center justify-center rounded-lg">
                    <div className="my-2">
                      <Upload className="size-6" />
                    </div>

                    <p className="mt-3 text-sm font-semibold">Drop files here</p>
                  </div>
                </div>
              )}
            </div>
          );
        }

        ```
      </Step>

      <Step>
        **Update the import paths to match your project setup.**
      </Step>
    </Steps>
  </Tab>
</Tabs>

Usage [#usage]

The `<UploadDropzone />` component should be used with the `useUploadFiles` hook.

```tsx
'use client';

import { useUploadFiles } from '@better-upload/client';
import { UploadDropzone } from '@/components/ui/upload-dropzone';

export function Uploader() {
  const { control } = useUploadFiles({
    route: 'images',
  });

  return <UploadDropzone control={control} accept="image/*" />;
}
```

When clicked, the dropzone will open a file picker dialog. When selected or dropped, the files will be uploaded to the desired route.

Description [#description]

You can customize the description shown in the dropzone. You can pass a string, or an object with the following properties:

* `maxFiles`: The maximum number of files that can be uploaded.
* `maxFileSize`: The maximum size of the files that can be uploaded, use a formatted string (e.g. `10MB`).
* `fileTypes`: The file types that can be uploaded.

```tsx
<UploadDropzone
  control={control}
  accept="image/*"
  description={{
    maxFiles: 4,
    maxFileSize: '2MB',
    fileTypes: 'JPEG, PNG, GIF',
  }}
/>
```

<Callout>
  Note that this is only cosmetic and does not enforce any restrictions
  client-side.
</Callout>

Props [#props]

<TypeTable
  type="{
  control: {
    type: 'object',
    description: 'Control object returned by the useUploadFiles hook.',
    required: true,
  },
  id: {
    type: 'string',
    description: 'The id of the input element.',
  },
  accept: {
    type: 'string',
    description: 'The file types that the input should accept.',
  },
  description: {
    type: 'string | object',
    description:
      'The description to show in the dropzone. Object for max files, max file size, and file types. You can also return a raw string.',
  },
  metadata: {
    type: 'Record<string, unknown>',
    description:
      'Metadata to send to your server on upload. Needs to be JSON serializable.',
  },
  uploadOverride: {
    type: 'function',
    description:
      'Override the default upload function. For example, set files in an array, and upload them after form submission.',
  },
}"
/>


# Upload Progress (/docs/components/upload-progress)





Preview [#preview]

<Showcase>
  <UploadProgressDemo />
</Showcase>

Installation [#installation]

<Tabs items="['CLI', 'Manual']">
  <Tab value="CLI">
    ```bash
    npx shadcn@latest add @better-upload/upload-progress
    ```
  </Tab>

  <Tab value="Manual">
    <Steps>
      <Step>
        **Install the following dependencies:**

        <CodeBlockTabs defaultValue="npm" groupId="package-manager">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npm i lucide-react react-dropzone
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm add lucide-react react-dropzone
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn add lucide-react react-dropzone
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun add lucide-react react-dropzone
            ```
          </CodeBlockTab>
        </CodeBlockTabs>

        Make sure to have [shadcn/ui](https://ui.shadcn.com/docs/installation) set up in your project, with the [progress](https://ui.shadcn.com/docs/components/progress) component installed.
      </Step>

      <Step>
        **Copy and paste the following code into your project.**

        ```tsx title='components/ui/upload-progress.tsx'
        import { Progress } from '@/components/ui/progress';
        import { cn } from '@/lib/utils';
        import type { UploadHookControl } from '@better-upload/client';
        import { formatBytes } from '@better-upload/client/helpers';
        import { Dot, File } from 'lucide-react';

        type UploadProgressProps = {
          control: UploadHookControl<true>;

          // Add any additional props you need.
        };

        export function UploadProgress({
          control: { progresses },
        }: UploadProgressProps) {
          return (
            <div className="grid gap-2">
              {progresses.map((progress) => (
                <div
                  key={progress.objectInfo.key}
                  className={cn(
                    'dark:bg-input/10 flex items-center gap-2 rounded-lg border bg-transparent p-3',
                    {
                      'bg-red-500/[0.04]! border-red-500/60':
                        progress.status === 'failed',
                    }
                  )}
                >
                  <FileIcon type={progress.type} />

                  <div className="grid grow gap-1">
                    <div className="flex items-center gap-0.5">
                      <p className="max-w-40 truncate text-sm font-medium">
                        {progress.name}
                      </p>
                      <Dot className="text-muted-foreground size-4" />
                      <p className="text-muted-foreground text-xs">
                        {formatBytes(progress.size)}
                      </p>
                    </div>

                    <div className="flex h-4 items-center">
                      {progress.progress < 1 && progress.status !== 'failed' ? (
                        <Progress className="h-1.5" value={progress.progress * 100} />
                      ) : progress.status === 'failed' ? (
                        <p className="text-xs text-red-500">Failed</p>
                      ) : (
                        <p className="text-muted-foreground text-xs">Completed</p>
                      )}
                    </div>
                  </div>
                </div>
              ))}
            </div>
          );
        }

        const iconCaptions = {
          'image/': 'IMG',
          'video/': 'VID',
          'audio/': 'AUD',
          'application/pdf': 'PDF',
          'application/zip': 'ZIP',
          'application/x-rar-compressed': 'RAR',
          'application/x-7z-compressed': '7Z',
          'application/x-tar': 'TAR',
          'application/json': 'JSON',
          'application/javascript': 'JS',
          'text/plain': 'TXT',
          'text/csv': 'CSV',
          'text/html': 'HTML',
          'text/css': 'CSS',
          'application/xml': 'XML',
          'application/x-sh': 'SH',
          'application/x-python-code': 'PY',
          'application/x-executable': 'EXE',
          'application/x-disk-image': 'ISO',
        };

        function FileIcon({ type }: { type: string }) {
          const caption = Object.entries(iconCaptions).find(([key]) =>
            type.startsWith(key)
          )?.[1];

          return (
            <div className="relative shrink-0">
              <File className="text-muted-foreground size-12" strokeWidth={1} />

              {caption && (
                <span className="bg-primary text-primary-foreground absolute bottom-2.5 left-0.5 select-none rounded px-1 py-px text-xs font-semibold">
                  {caption}
                </span>
              )}
            </div>
          );
        }

        ```
      </Step>

      <Step>
        **Update the import paths to match your project setup.**
      </Step>
    </Steps>
  </Tab>
</Tabs>

Usage [#usage]

The `<UploadProgress />` component should be used with the `useUploadFiles` hook.

```tsx
'use client';

import { useUploadFiles } from '@better-upload/client';
import { UploadProgress } from '@/components/ui/upload-progress';

export function Uploader() {
  const { control } = useUploadFiles({
    route: 'images',
  });

  return <UploadProgress control={control} />;
}
```

This component should probably be used alongside another component, such as [`<UploadDropzone />`](/docs/components/upload-dropzone), to trigger the file uploads.

```tsx
'use client';

import { useUploadFiles } from '@better-upload/client';
import { UploadDropzone } from '@/components/ui/upload-dropzone';
import { UploadProgress } from '@/components/ui/upload-progress';

export function Uploader() {
  const { control } = useUploadFiles({
    route: 'images',
  });

  return (
    <div className="flex flex-col gap-4">
      <UploadDropzone control={control} accept="image/*" />
      <UploadProgress control={control} />
    </div>
  );
}
```

Props [#props]

<TypeTable
  type="{
  control: {
    type: 'object',
    description: 'Control object returned by the useUploadFiles hook.',
    required: true,
  },
}"
/>


# TanStack Query (/docs/guides/tanstack-query)



If you prefer to use TanStack Query instead of the hooks provided by Better Upload, you can do so by using the `uploadFile` and `uploadFiles` functions with the `useMutation` hook from TanStack Query.

Example [#example]

The complete code for a simple uploader is below.

<CodeBlockTabs defaultValue="Multiple files">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Multiple files">
      Multiple files
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Single files">
      Single files
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Multiple files">
    ```tsx
    'use client';

    import { uploadFiles } from '@better-upload/client';
    import { useMutation } from '@tanstack/react-query';

    export function Uploader() {
      const { mutate: upload, isPending } = useMutation({
        mutationFn: async (files: File[]) => {
          return uploadFiles({
            files,
            route: 'form',
            onFileStateChange: ({ file }) => {
              // you handle the progress of each file
              console.log(file);
            },
          });
        },
        onSuccess: ({ files, failedFiles, metadata }) => {
          console.log({
            files,
            failedFiles,
            metadata,
          });
        },
        onError: (error) => {
          console.error(error);
        },
      });

      return (
        <input
          type="file"
          multiple
          disabled={isPending}
          onChange={(e) => {
            if (e.target.files) {
              upload(Array.from(e.target.files));
            }
          }}
        />
      );
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Single files">
    ```tsx
    'use client';

    import { uploadFile } from '@better-upload/client';
    import { useMutation } from '@tanstack/react-query';

    export function Uploader() {
      const { mutate: upload, isPending } = useMutation({
        mutationFn: async (file: File) => {
          return uploadFile({
            file,
            route: 'form',
            onFileStateChange: ({ file }) => {
              // you handle the progress of the file
              console.log(file);
            },
          });
        },
        onSuccess: ({ file, metadata }) => {
          console.log({
            file,
            metadata,
          });
        },
        onError: (error) => {
          console.error(error);
        },
      });

      return (
        <input
          type="file"
          disabled={isPending}
          onChange={(e) => {
            if (e.target.files?.[0]) {
              upload(e.target.files[0]);
            }
          }}
        />
      );
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Tracking upload state [#tracking-upload-state]

Note that by directly using the upload functions, you need to track the state of each file upload yourself. This is simple to do, an example for multiple files is below.

```tsx
'use client';

import {
  type FileUploadInfo,
  type UploadStatus,
  uploadFiles,
} from '@better-upload/client';
import { useMutation } from '@tanstack/react-query';
import { useState } from 'react';

export function Uploader() {
  // [!code highlight:3]
  const [uploadState, setUploadState] = useState(
    () => new Map<string, FileUploadInfo<UploadStatus>>()
  );

  const { mutate: upload, isPending } = useMutation({
    mutationFn: async (files: File[]) => {
      return uploadFiles({
        files,
        route: 'form',
        onFileStateChange: ({ file }) => {
          // [!code highlight:3]
          setUploadState((prev) =>
            new Map(prev).set(file.objectInfo.key, file)
          );
        },
      });
    },
  });

  return (
    <input
      type="file"
      multiple
      disabled={isPending}
      onChange={(e) => {
        if (e.target.files) {
          upload(Array.from(e.target.files));
        }
      }}
    />
  );
}
```


# React Hook Form (/docs/guides/forms/react-hook-form)



It's common for file uploads to be part of a form. In this guide, we'll take a look at how to add file uploads to a form built with **React Hook Form**. This guide is based on the shadcn/ui [form guide](https://ui.shadcn.com/docs/forms/react-hook-form) and will use the [`<Field />`](https://ui.shadcn.com/docs/components/field) component.

We'll cover multiple file uploads, but the same principles apply for single file uploads.

Form [#form]

<Steps>
  <Step>
    Installation [#installation]

    Install the following shadcn/ui components. Make sure to also have React Hook Form and Zod installed.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add field input button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add field input button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add field input button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add field input button
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Step>

  <Step>
    Setup upload route [#setup-upload-route]

    Setup your upload route. Use your preferred framework, but for this example, we'll use Next.js.

    ```ts title="app/api/upload/route.ts"
    import { route, type Router } from '@better-upload/server';
    import { toRouteHandler } from '@better-upload/server/adapters/next';
    import { aws } from '@better-upload/server/clients';

    const router: Router = {
      client: aws(),
      bucketName: 'my-bucket',
      routes: {
        form: route({
          multipleFiles: true,
          maxFiles: 5,
          maxFileSize: 1024 * 1024 * 5, // 5MB
          onBeforeUpload() {
            return {
              generateObjectInfo: ({ file }) => ({ key: `form/${file.name}` }),
            };
          },
        }),
      },
    };

    export const { POST } = toRouteHandler(router);
    ```
  </Step>

  <Step>
    Define form schema [#define-form-schema]

    We'll start by defining the shape of our form using a Zod schema. It contains two fields:

    * `folderName`: For an arbitrary text input.
    * `objectKeys`: For the uploaded files, stores the S3 object keys.

    ```tsx title="form.tsx"
    import * as z from 'zod';

    const formSchema = z.object({
      folderName: z.string().min(1, 'Folder name is required.'),
      objectKeys: z.array(z.string()).min(1, 'Upload at least one file.'),
    });
    ```
  </Step>

  <Step>
    Setup the form [#setup-the-form]

    Next, we'll use the `useForm` hook from React Hook Form to create our form instance, along with the `useUploadFiles` hook to handle file uploads.

    ```tsx title="form.tsx"
    import { useUploadFiles } from '@better-upload/client';
    import { zodResolver } from '@hookform/resolvers/zod';
    import { useForm } from 'react-hook-form';
    import * as z from 'zod';

    const formSchema = z.object({
      folderName: z.string().min(1, 'Folder name is required.'),
      objectKeys: z.array(z.string()).min(1, 'Upload at least one file.'),
    });

    export function FormUploader() {
      const form = useForm<z.infer<typeof formSchema>>({
        resolver: zodResolver(formSchema),
        defaultValues: {
          folderName: '',
          objectKeys: [],
        },
      });

      const uploader = useUploadFiles({
        route: 'form',
        onUploadComplete: ({ files }) => {
          form.setValue(
            'objectKeys',
            files.map((file) => file.objectInfo.key)
          );
        },
        onError: (error) => {
          form.setError('objectKeys', {
            message: error.message || 'An error occurred.',
          });
        },
      });

      function onSubmit(data: z.infer<typeof formSchema>) {
        // call your API here
        console.log(data);
      }

      return (
        <form onSubmit={form.handleSubmit(onSubmit)}>
          {/* ... */}
          {/* Build the form here */}
          {/* ... */}
        </form>
      );
    }
    ```
  </Step>

  <Step>
    Build the form [#build-the-form]

    We can now build the form using the `<Controller />` component from React Hook Form and the `<UploadDropzone />` component for the file uploads.

    ```tsx title="form.tsx"
    'use client';

    import { useUploadFiles } from '@better-upload/client';
    import { zodResolver } from '@hookform/resolvers/zod';
    import { Controller, useForm } from 'react-hook-form';
    import * as z from 'zod';

    import { Button } from '@/components/ui/button';
    import {
      Card,
      CardContent,
      CardDescription,
      CardFooter,
      CardHeader,
      CardTitle,
    } from '@/components/ui/card';
    import {
      Field,
      FieldError,
      FieldGroup,
      FieldLabel,
    } from '@/components/ui/field';
    import { Input } from '@/components/ui/input';
    import { UploadDropzone } from '@/components/ui/upload-dropzone';

    const formSchema = z.object({
      folderName: z.string().min(1, 'Folder name is required.'),
      objectKeys: z.array(z.string()).min(1, 'Upload at least one file.'),
    });

    export function FormUploader() {
      const form = useForm<z.infer<typeof formSchema>>({
        resolver: zodResolver(formSchema),
        defaultValues: {
          folderName: '',
          objectKeys: [],
        },
      });

      const uploader = useUploadFiles({
        route: 'form',
        onUploadComplete: ({ files }) => {
          form.setValue(
            'objectKeys',
            files.map((file) => file.objectInfo.key)
          );
        },
        onError: (error) => {
          form.setError('objectKeys', {
            message: error.message || 'An error occurred.',
          });
        },
      });

      function onSubmit(data: z.infer<typeof formSchema>) {
        // call your API here
        console.log(data);
      }

      return (
        <Card className="w-full sm:max-w-md">
          <CardHeader>
            <CardTitle>Form Uploader</CardTitle>
            <CardDescription>Upload files to a specific folder.</CardDescription>
          </CardHeader>
          <CardContent>
            <form id="form-rhf-demo" onSubmit={form.handleSubmit(onSubmit)}>
              <FieldGroup>
                <Controller
                  name="folderName"
                  control={form.control}
                  render={({ field, fieldState }) => (
                    <Field data-invalid={fieldState.invalid}>
                      <FieldLabel htmlFor="form-rhf-demo-folderName">
                        Folder name
                      </FieldLabel>
                      <Input
                        {...field}
                        id="form-rhf-demo-folderName"
                        aria-invalid={fieldState.invalid}
                        placeholder="my-folder"
                        autoComplete="off"
                      />
                      {fieldState.invalid && (
                        <FieldError errors={[fieldState.error]} />
                      )}
                    </Field>
                  )}
                />
                <Controller
                  name="objectKeys"
                  control={form.control}
                  render={({ fieldState }) => (
                    <Field data-invalid={fieldState.invalid}>
                      <FieldLabel htmlFor="form-rhf-demo-objectKeys">
                        Files
                      </FieldLabel>
                      <UploadDropzone
                        id="form-rhf-demo-objectKeys"
                        control={uploader.control}
                        description={{
                          maxFiles: 5,
                          maxFileSize: '5MB',
                        }}
                      />
                      {fieldState.invalid && (
                        <FieldError errors={[fieldState.error]} />
                      )}
                    </Field>
                  )}
                />
              </FieldGroup>
            </form>
          </CardContent>
          <CardFooter>
            <Field orientation="horizontal">
              <Button
                type="button"
                variant="outline"
                onClick={() => {
                  form.reset();
                  uploader.reset();
                }}
              >
                Reset
              </Button>
              <Button
                type="submit"
                form="form-rhf-demo"
                disabled={uploader.isPending}
              >
                Submit
              </Button>
            </Field>
          </CardFooter>
        </Card>
      );
    }
    ```
  </Step>

  <Accordions>
    <Accordion title="Hiding dropzone after upload">
      Let's hide the dropzone after the user has uploaded files. We can do this by using the `uploadedFiles` array returned by the `useUploadFiles` hook.

      ```tsx
      export function FormUploader() {
        // ...

        return (
          <Card className="w-full sm:max-w-md">
            {/* ... */}

            <CardContent>
              <form id="form-rhf-demo" onSubmit={form.handleSubmit(onSubmit)}>
                <FieldGroup>
                  {/* ... */}

                  <Controller
                    name="objectKeys"
                    control={form.control}
                    // [!code highlight]
                    render={({ field, fieldState }) => (
                      <Field data-invalid={fieldState.invalid}>
                        <FieldLabel htmlFor="form-rhf-demo-objectKeys">
                          Files
                        </FieldLabel>
                        {/* [!code highlight:18] */}
                        {field.value.length > 0 ? (
                          <div className="flex flex-col">
                            {uploader.uploadedFiles.map((file) => (
                              <span key={file.objectInfo.key} className="text-sm">
                                {file.name}
                              </span>
                            ))}
                          </div>
                        ) : (
                          <UploadDropzone
                            id="form-rhf-demo-objectKeys"
                            control={uploader.control}
                            description={{
                              maxFiles: 5,
                              maxFileSize: '5MB',
                            }}
                          />
                        )}
                        {fieldState.invalid && (
                          <FieldError errors={[fieldState.error]} />
                        )}
                      </Field>
                    )}
                  />
                </FieldGroup>
              </form>
            </CardContent>

            {/* ... */}
          </Card>
        );
      }
      ```
    </Accordion>
  </Accordions>
</Steps>

Upload on form submit [#upload-on-form-submit]

In this example, we only upload the files after the user clicks on the submit button. We'll use the `uploadOverride` prop to override the default behavior of the `<UploadDropzone />`.

```tsx title="form.tsx"
'use client';

import { useUploadFiles } from '@better-upload/client';
import { zodResolver } from '@hookform/resolvers/zod';
import { Controller, useForm } from 'react-hook-form';
import * as z from 'zod';

import { Button } from '@/components/ui/button';
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';
import {
  Field,
  FieldError,
  FieldGroup,
  FieldLabel,
} from '@/components/ui/field';
import { Input } from '@/components/ui/input';
import { UploadDropzone } from '@/components/ui/upload-dropzone';

const formSchema = z.object({
  folderName: z.string().min(1, 'Folder name is required.'),
  files: z.array(z.file()).min(1, 'Upload at least one file.'),
  // for Zod v3: z.array(z.instanceof(File)).min(1, 'Upload at least one file.'),
});

export function FormUploader() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
    defaultValues: {
      folderName: '',
      files: [],
    },
  });

  const uploader = useUploadFiles({
    route: 'form',
    onError: (error) => {
      form.setError('files', {
        message: error.message || 'An error occurred.',
      });
    },
  });

  async function onSubmit(data: z.infer<typeof formSchema>) {
    const { files } = await uploader.upload(data.files);

    // call your API here
    console.log({
      folderName: data.folderName,
      objectKeys: files.map((file) => file.objectInfo.key),
    });
  }

  return (
    <Card className="w-full sm:max-w-md">
      <CardHeader>
        <CardTitle>Form Uploader</CardTitle>
        <CardDescription>Upload files to a specific folder.</CardDescription>
      </CardHeader>
      <CardContent>
        <form id="form-rhf-demo" onSubmit={form.handleSubmit(onSubmit)}>
          <FieldGroup>
            <Controller
              name="folderName"
              control={form.control}
              render={({ field, fieldState }) => (
                <Field data-invalid={fieldState.invalid}>
                  <FieldLabel htmlFor="form-rhf-demo-folderName">
                    Folder name
                  </FieldLabel>
                  <Input
                    {...field}
                    id="form-rhf-demo-folderName"
                    aria-invalid={fieldState.invalid}
                    placeholder="my-folder"
                    autoComplete="off"
                  />
                  {fieldState.invalid && (
                    <FieldError errors={[fieldState.error]} />
                  )}
                </Field>
              )}
            />
            <Controller
              name="files"
              control={form.control}
              render={({ field, fieldState }) => (
                <Field data-invalid={fieldState.invalid}>
                  <FieldLabel htmlFor="form-rhf-demo-files">Files</FieldLabel>
                  {field.value.length > 0 ? (
                    <div className="flex flex-col">
                      {field.value.map((file) => (
                        <span key={file.name} className="text-sm">
                          {file.name}
                        </span>
                      ))}
                    </div>
                  ) : (
                    <UploadDropzone
                      id="form-rhf-demo-files"
                      control={uploader.control}
                      description={{
                        maxFiles: 5,
                        maxFileSize: '5MB',
                      }}
                      uploadOverride={(files) => {
                        field.onChange(Array.from(files));
                      }}
                    />
                  )}
                  {fieldState.invalid && (
                    <FieldError errors={[fieldState.error]} />
                  )}
                </Field>
              )}
            />
          </FieldGroup>
        </form>
      </CardContent>
      <CardFooter>
        <Field orientation="horizontal">
          <Button
            type="button"
            variant="outline"
            onClick={() => {
              form.reset();
              uploader.reset();
            }}
          >
            Reset
          </Button>
          <Button
            type="submit"
            form="form-rhf-demo"
            disabled={uploader.isPending}
          >
            Submit
          </Button>
        </Field>
      </CardFooter>
    </Card>
  );
}
```


# TanStack Form (/docs/guides/forms/tanstack-form)



It's common for file uploads to be part of a form. In this guide, we'll take a look at how to add file uploads to a form built with **TanStack Form**. This guide is based on the shadcn/ui [form guide](https://ui.shadcn.com/docs/forms/tanstack-form) and will use the [`<Field />`](https://ui.shadcn.com/docs/components/field) component.

We'll cover multiple file uploads, but the same principles apply for single file uploads.

Form [#form]

<Steps>
  <Step>
    Installation [#installation]

    Install the following shadcn/ui components. Make sure to also have TanStack Form and Zod installed.

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add field input button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add field input button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add field input button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add field input button
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Step>

  <Step>
    Setup upload route [#setup-upload-route]

    Setup your upload route. Use your preferred framework, but for this example, we'll use Next.js.

    ```ts title="app/api/upload/route.ts"
    import { route, type Router } from '@better-upload/server';
    import { toRouteHandler } from '@better-upload/server/adapters/next';
    import { aws } from '@better-upload/server/clients';

    const router: Router = {
      client: aws(),
      bucketName: 'my-bucket',
      routes: {
        form: route({
          multipleFiles: true,
          maxFiles: 5,
          maxFileSize: 1024 * 1024 * 5, // 5MB
          onBeforeUpload() {
            return {
              generateObjectInfo: ({ file }) => ({ key: `form/${file.name}` }),
            };
          },
        }),
      },
    };

    export const { POST } = toRouteHandler(router);
    ```
  </Step>

  <Step>
    Define form schema [#define-form-schema]

    We'll start by defining the shape of our form using a Zod schema. It contains two fields:

    * `folderName`: For an arbitrary text input.
    * `objectKeys`: For the uploaded files, stores the S3 object keys.

    ```tsx title="form.tsx"
    import * as z from 'zod';

    const formSchema = z.object({
      folderName: z.string().min(1, 'Folder name is required.'),
      objectKeys: z.array(z.string()).min(1, 'Upload at least one file.'),
    });
    ```
  </Step>

  <Step>
    Setup the form [#setup-the-form]

    Use the `useForm` hook from TanStack Form to create your form instance with Zod validation, along with the `useUploadFiles` hook to handle file uploads.

    ```tsx title="form.tsx"
    import { useUploadFiles } from '@better-upload/client';
    import { useForm } from '@tanstack/react-form';
    import * as z from 'zod';

    const formSchema = z.object({
      folderName: z.string().min(1, 'Folder name is required.'),
      objectKeys: z.array(z.string()).min(1, 'Upload at least one file.'),
    });

    export function FormUploader() {
      const form = useForm({
        defaultValues: {
          folderName: '',
          objectKeys: [] as string[],
        },
        validators: {
          onSubmit: formSchema,
        },
        onSubmit: ({ value }) => {
          // call your API here
          console.log(value);
        },
      });

      const uploader = useUploadFiles({
        route: 'form',
        onUploadComplete: ({ files }) => {
          form.setFieldValue(
            'objectKeys',
            files.map((file) => file.objectInfo.key)
          );
        },
      });

      return (
        <form
          onSubmit={(e) => {
            e.preventDefault();
            form.handleSubmit();
          }}
        >
          {/* ... */}
        </form>
      );
    }
    ```
  </Step>

  <Step>
    Build the form [#build-the-form]

    We can now build the form using the `form.Field` component from TanStack Form and the `<UploadDropzone />` component for the file uploads.

    ```tsx title="form.tsx"
    'use client';

    import { useUploadFiles } from '@better-upload/client';
    import { useForm } from '@tanstack/react-form';
    import * as z from 'zod';

    import { Button } from '@/components/ui/button';
    import {
      Card,
      CardContent,
      CardDescription,
      CardFooter,
      CardHeader,
      CardTitle,
    } from '@/components/ui/card';
    import {
      Field,
      FieldError,
      FieldGroup,
      FieldLabel,
    } from '@/components/ui/field';
    import { Input } from '@/components/ui/input';
    import { UploadDropzone } from '@/components/ui/upload-dropzone';

    const formSchema = z.object({
      folderName: z.string().min(1, 'Folder name is required.'),
      objectKeys: z.array(z.string()).min(1, 'Upload at least one file.'),
    });

    export function FormUploader() {
      const form = useForm({
        defaultValues: {
          folderName: '',
          objectKeys: [] as string[],
        },
        validators: {
          onSubmit: formSchema,
        },
        onSubmit: ({ value }) => {
          // call your API here
          console.log(value);
        },
      });

      const uploader = useUploadFiles({
        route: 'form',
        onUploadComplete: ({ files }) => {
          form.setFieldValue(
            'objectKeys',
            files.map((file) => file.objectInfo.key)
          );
        },
      });

      return (
        <Card className="w-full sm:max-w-md">
          <CardHeader>
            <CardTitle>Form Uploader</CardTitle>
            <CardDescription>Upload files to a specific folder.</CardDescription>
          </CardHeader>
          <CardContent>
            <form
              id="uploader-form"
              onSubmit={(e) => {
                e.preventDefault();
                form.handleSubmit();
              }}
            >
              <FieldGroup>
                <form.Field
                  name="folderName"
                  children={(field) => {
                    const isInvalid =
                      field.state.meta.isTouched && !field.state.meta.isValid;
                    return (
                      <Field data-invalid={isInvalid}>
                        <FieldLabel htmlFor={field.name}>Folder name</FieldLabel>
                        <Input
                          id={field.name}
                          name={field.name}
                          value={field.state.value}
                          onBlur={field.handleBlur}
                          onChange={(e) => field.handleChange(e.target.value)}
                          aria-invalid={isInvalid}
                          placeholder="my-folder"
                          autoComplete="off"
                        />
                        {isInvalid && (
                          <FieldError errors={field.state.meta.errors} />
                        )}
                      </Field>
                    );
                  }}
                />
                <form.Field
                  name="objectKeys"
                  children={(field) => {
                    const isInvalid =
                      (field.state.meta.isTouched && !field.state.meta.isValid) ||
                      uploader.isError;
                    return (
                      <Field data-invalid={isInvalid}>
                        <FieldLabel htmlFor={field.name}>Folder name</FieldLabel>
                        <UploadDropzone
                          id={field.name}
                          control={uploader.control}
                          description={{
                            maxFiles: 5,
                            maxFileSize: '5MB',
                          }}
                        />
                        {isInvalid && (
                          <FieldError
                            errors={
                              uploader.error
                                ? [{ message: uploader.error.message }]
                                : field.state.meta.errors
                            }
                          />
                        )}
                      </Field>
                    );
                  }}
                />
              </FieldGroup>
            </form>
          </CardContent>
          <CardFooter>
            <Field orientation="horizontal">
              <Button
                type="button"
                variant="outline"
                onClick={() => {
                  form.reset();
                  uploader.reset();
                }}
              >
                Reset
              </Button>
              <Button
                type="submit"
                form="uploader-form"
                disabled={uploader.isPending}
              >
                Submit
              </Button>
            </Field>
          </CardFooter>
        </Card>
      );
    }
    ```
  </Step>

  <Accordions>
    <Accordion title="Hiding dropzone after upload">
      Let's hide the dropzone after the user has uploaded files. We can do this by using the `uploadedFiles` array returned by the `useUploadFiles` hook.

      ```tsx
      export function FormUploader() {
        // ...

        return (
          <Card className="w-full sm:max-w-md">
            {/* ... */}

            <CardContent>
              <form
                id="uploader-form"
                onSubmit={(e) => {
                  e.preventDefault();
                  form.handleSubmit();
                }}
              >
                <FieldGroup>
                  {/* ... */}

                  <form.Field
                    name="objectKeys"
                    children={(field) => {
                      const isInvalid =
                        (field.state.meta.isTouched && !field.state.meta.isValid) ||
                        uploader.isError;
                      return (
                        <Field data-invalid={isInvalid}>
                          <FieldLabel htmlFor={field.name}>Folder name</FieldLabel>
                          {field.state.value.length > 0 ? (
                            <div className="flex flex-col">
                              {uploader.uploadedFiles.map((file) => (
                                <span key={file.objectInfo.key} className="text-sm">
                                  {file.name}
                                </span>
                              ))}
                            </div>
                          ) : (
                            <UploadDropzone
                              id={field.name}
                              control={uploader.control}
                              description={{
                                maxFiles: 5,
                                maxFileSize: '5MB',
                              }}
                            />
                          )}
                          {isInvalid && (
                            <FieldError
                              errors={
                                uploader.error
                                  ? [{ message: uploader.error.message }]
                                  : field.state.meta.errors
                              }
                            />
                          )}
                        </Field>
                      );
                    }}
                  />
                </FieldGroup>
              </form>
            </CardContent>

            {/* ... */}
          </Card>
        );
      }
      ```
    </Accordion>
  </Accordions>
</Steps>

Upload on form submit [#upload-on-form-submit]

In this example, we only upload the files after the user clicks on the submit button. We'll use the `uploadOverride` prop to override the default behavior of the `<UploadDropzone />`.

```tsx title="form.tsx"
'use client';

import { useUploadFiles } from '@better-upload/client';
import { useForm } from '@tanstack/react-form';
import * as z from 'zod';

import { Button } from '@/components/ui/button';
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';
import {
  Field,
  FieldError,
  FieldGroup,
  FieldLabel,
} from '@/components/ui/field';
import { Input } from '@/components/ui/input';
import { UploadDropzone } from '@/components/ui/upload-dropzone';

const formSchema = z.object({
  folderName: z.string().min(1, 'Folder name is required.'),
  files: z.array(z.file()).min(1, 'Upload at least one file.'),
  // for Zod v3: z.array(z.instanceof(File)).min(1, 'Upload at least one file.'),
});

export function FormUploader() {
  const form = useForm({
    defaultValues: {
      folderName: '',
      files: [] as File[],
    },
    validators: {
      onSubmit: formSchema,
    },
    onSubmit: async ({ value }) => {
      const { files } = await uploader.upload(value.files);

      // call your API here
      console.log({
        folderName: value.folderName,
        objectKeys: files.map((file) => file.objectInfo.key),
      });
    },
  });

  const uploader = useUploadFiles({
    route: 'form',
  });

  return (
    <Card className="w-full sm:max-w-md">
      <CardHeader>
        <CardTitle>Form Uploader</CardTitle>
        <CardDescription>Upload files to a specific folder.</CardDescription>
      </CardHeader>
      <CardContent>
        <form
          id="uploader-form"
          onSubmit={(e) => {
            e.preventDefault();
            form.handleSubmit();
          }}
        >
          <FieldGroup>
            <form.Field
              name="folderName"
              children={(field) => {
                const isInvalid =
                  field.state.meta.isTouched && !field.state.meta.isValid;
                return (
                  <Field data-invalid={isInvalid}>
                    <FieldLabel htmlFor={field.name}>Folder name</FieldLabel>
                    <Input
                      id={field.name}
                      name={field.name}
                      value={field.state.value}
                      onBlur={field.handleBlur}
                      onChange={(e) => field.handleChange(e.target.value)}
                      aria-invalid={isInvalid}
                      placeholder="my-folder"
                      autoComplete="off"
                    />
                    {isInvalid && (
                      <FieldError errors={field.state.meta.errors} />
                    )}
                  </Field>
                );
              }}
            />
            <form.Field
              name="files"
              children={(field) => {
                const isInvalid =
                  (field.state.meta.isTouched && !field.state.meta.isValid) ||
                  uploader.isError;
                return (
                  <Field data-invalid={isInvalid}>
                    <FieldLabel htmlFor={field.name}>Folder name</FieldLabel>
                    {field.state.value.length > 0 ? (
                      <div className="flex flex-col">
                        {field.state.value.map((file) => (
                          <span key={file.name} className="text-sm">
                            {file.name}
                          </span>
                        ))}
                      </div>
                    ) : (
                      <UploadDropzone
                        id={field.name}
                        control={uploader.control}
                        description={{
                          maxFiles: 5,
                          maxFileSize: '5MB',
                        }}
                        uploadOverride={(files) => {
                          field.handleChange(Array.from(files));
                        }}
                      />
                    )}
                    {isInvalid && (
                      <FieldError
                        errors={
                          uploader.error
                            ? [{ message: uploader.error.message }]
                            : field.state.meta.errors
                        }
                      />
                    )}
                  </Field>
                );
              }}
            />
          </FieldGroup>
        </form>
      </CardContent>
      <CardFooter>
        <Field orientation="horizontal">
          <Button
            type="button"
            variant="outline"
            onClick={() => {
              form.reset();
              uploader.reset();
            }}
          >
            Reset
          </Button>
          <Button
            type="submit"
            form="uploader-form"
            disabled={uploader.isPending}
          >
            Submit
          </Button>
        </Field>
      </CardFooter>
    </Card>
  );
}
```