---
title: "useConvexR2Upload"
description: "Reference for the Nuxt-only Cloudflare R2 upload helper."
canonical_url: "https://nuxt-convex.onmax.me/api-reference/use-convex-r2-upload"
---
# useConvexR2Upload

> Reference for the Nuxt-only Cloudflare R2 upload helper.

`useConvexR2Upload` uploads files to Cloudflare R2 through the Convex R2 component and then syncs metadata back through Convex.

## Import

```ts
const { upload, progress, isUploading, error } = useConvexR2Upload(api.r2)
```

`useConvexR2Upload` is available as a Nuxt auto-import when `convex.r2` is enabled.

## Signature

```ts
function useConvexR2Upload(api: {
  generateUploadUrl: FunctionReference<'mutation'>
  syncMetadata: FunctionReference<'mutation'>
}, options?: {
  onSuccess?: (key: string, file: File) => void
  onError?: (error: Error) => void
  onProgress?: (progress: { loaded: number, total: number }) => void
}): {
  upload: (file: File) => Promise<string | null>
  isUploading: Readonly<Ref<boolean>>
  progress: Readonly<Ref<number>>
  error: Readonly<Ref<Error | null>>
}
```

## Behavior

- Client-only; calling `upload()` on the server returns `null` and sets an error
- Requests a signed upload URL from `generateUploadUrl`
- Uploads the file with `XMLHttpRequest`
- Calls `syncMetadata` after the upload succeeds
- Exposes byte-level progress through `onProgress` and the `progress` ref

## Related pages

- [Cloudflare R2](https://nuxt-convex.onmax.me/nuxt-module/cloudflare-r2)
- [R2](https://nuxt-convex.onmax.me/integrations/r2)


## Sitemap

See the full [sitemap](https://nuxt-convex.onmax.me/sitemap.md) for all pages.
