From 01c8f3bf5e17246006ebe263700ed6fb88fa5ed4 Mon Sep 17 00:00:00 2001
From: Benjamin Canac <canacb1@gmail.com>
Date: Wed, 16 Jul 2025 10:22:06 +0200
Subject: [PATCH] feat(FileUpload): new component

Co-Authored-By: Vachmara <55046446+vachmara@users.noreply.github.com>
---
 docs/content/3.components/file-upload.md      |  31 +++++
 .../app/pages/components/file-upload.vue      |   5 +
 playground/app/pages/index.vue                |  88 +++++++++++--
 playground/nuxt.config.ts                     |   4 +
 playground/server/api/blob.put.ts             |  12 ++
 src/runtime/components/FileUpload.vue         | 119 ++++++++++++++++++
 src/runtime/types/index.ts                    |   1 +
 src/theme/file-upload.ts                      |   5 +
 src/theme/index.ts                            |   1 +
 test/components/FileUpload.spec.ts            |  18 +++
 10 files changed, 275 insertions(+), 9 deletions(-)
 create mode 100644 docs/content/3.components/file-upload.md
 create mode 100644 playground/app/pages/components/file-upload.vue
 create mode 100644 playground/server/api/blob.put.ts
 create mode 100644 src/runtime/components/FileUpload.vue
 create mode 100644 src/theme/file-upload.ts
 create mode 100644 test/components/FileUpload.spec.ts

diff --git a/docs/content/3.components/file-upload.md b/docs/content/3.components/file-upload.md
new file mode 100644
index 00000000..f2f1bf54
--- /dev/null
+++ b/docs/content/3.components/file-upload.md
@@ -0,0 +1,31 @@
+---
+title: FileUpload
+description: ''
+links:
+  - label: GitHub
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/ui/tree/v3/src/runtime/components/FileUpload.vue
+navigation.badge: Soon
+---
+
+## Usage
+
+## Examples
+
+## API
+
+### Props
+
+:component-props
+
+### Slots
+
+:component-slots
+
+### Emits
+
+:component-emits
+
+## Theme
+
+:component-theme
diff --git a/playground/app/pages/components/file-upload.vue b/playground/app/pages/components/file-upload.vue
new file mode 100644
index 00000000..f931baf9
--- /dev/null
+++ b/playground/app/pages/components/file-upload.vue
@@ -0,0 +1,5 @@
+<template>
+  <div>
+    <UFileUpload />
+  </div>
+</template>
diff --git a/playground/app/pages/index.vue b/playground/app/pages/index.vue
index 991b8d12..057f52a8 100644
--- a/playground/app/pages/index.vue
+++ b/playground/app/pages/index.vue
@@ -1,11 +1,81 @@
-<template>
-  <div class="text-center">
-    <h1 class="font-semibold text-primary mb-1">
-      Playground
-    </h1>
+<script setup lang="ts">
+import * as z from 'zod'
+import type { FormSubmitEvent } from '@nuxt/ui'
 
-    <div class="flex items-center justify-center gap-1">
-      <UKbd value="meta" /> <UKbd value="K" />
-    </div>
-  </div>
+const MAX_FILE_SIZE = 2 * 1024 * 1024 // 2MB
+const MIN_DIMENSIONS = { width: 200, height: 200 }
+const MAX_DIMENSIONS = { width: 4096, height: 4096 }
+const ACCEPTED_IMAGE_TYPES = ['image/jpeg', 'image/jpg', 'image/png', 'image/webp']
+
+const formatBytes = (bytes: number, decimals = 2) => {
+  if (bytes === 0) return '0 Bytes'
+  const k = 1024
+  const dm = decimals < 0 ? 0 : decimals
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']
+  const i = Math.floor(Math.log(bytes) / Math.log(k))
+  return Number.parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i]
+}
+
+const schema = z.object({
+  avatar: z
+    .instanceof(File, {
+      message: 'Please select an image file.'
+    })
+    .refine(file => file.size <= MAX_FILE_SIZE, {
+      message: `The image is too large. Please choose an image smaller than ${formatBytes(MAX_FILE_SIZE)}.`
+    })
+    .refine(file => ACCEPTED_IMAGE_TYPES.includes(file.type), {
+      message: 'Please upload a valid image file (JPEG, PNG, or WebP).'
+    })
+    .refine(
+      file =>
+        new Promise((resolve) => {
+          const reader = new FileReader()
+          reader.onload = (e) => {
+            const img = new Image()
+            img.onload = () => {
+              const meetsDimensions
+                  = img.width >= MIN_DIMENSIONS.width
+                    && img.height >= MIN_DIMENSIONS.height
+                    && img.width <= MAX_DIMENSIONS.width
+                    && img.height <= MAX_DIMENSIONS.height
+              resolve(meetsDimensions)
+            }
+            img.src = e.target?.result as string
+          }
+          reader.readAsDataURL(file)
+        }),
+      {
+        message: `The image dimensions are invalid. Please upload an image between ${MIN_DIMENSIONS.width}x${MIN_DIMENSIONS.height} and ${MAX_DIMENSIONS.width}x${MAX_DIMENSIONS.height} pixels.`
+      }
+    )
+})
+
+type schema = z.output<typeof schema>
+
+const state = reactive<Partial<schema>>({
+  avatar: undefined
+})
+
+const upload = useUpload('/api/blob', { method: 'PUT' })
+
+async function onSubmit(event: FormSubmitEvent<schema>) {
+  const res = await upload(event.data.avatar)
+
+  console.log(res)
+}
+</script>
+
+<template>
+  <UForm :schema="schema" :state="state" class="flex flex-col gap-4" @submit="onSubmit">
+    <UFormField name="avatar" label="Avatar" description="JPG, GIF or PNG. 1MB Max.">
+      <UFileUpload v-slot="{ open, previewUrls }" v-model="state.avatar" class="flex flex-wrap items-center gap-3" accept="image/*">
+        <UAvatar size="lg" :src="previewUrls?.[0]" icon="i-lucide-image" />
+
+        <UButton label="Choose" color="neutral" @click="open()" />
+      </UFileUpload>
+    </UFormField>
+
+    <UButton label="Submit" type="submit" block />
+  </UForm>
 </template>
diff --git a/playground/nuxt.config.ts b/playground/nuxt.config.ts
index 94ffb6da..a1c6890b 100644
--- a/playground/nuxt.config.ts
+++ b/playground/nuxt.config.ts
@@ -16,6 +16,10 @@ export default defineNuxtConfig({
 
   compatibilityDate: '2024-07-09',
 
+  hub: {
+    blob: true
+  },
+
   vite: {
     optimizeDeps: {
       // prevents reloading page when navigating between components
diff --git a/playground/server/api/blob.put.ts b/playground/server/api/blob.put.ts
new file mode 100644
index 00000000..cf1a2500
--- /dev/null
+++ b/playground/server/api/blob.put.ts
@@ -0,0 +1,12 @@
+export default eventHandler(async (event) => {
+  return hubBlob().handleUpload(event, {
+    formKey: 'files', // read file or files form the `formKey` field of request body (body should be a `FormData` object)
+    multiple: true, // when `true`, the `formKey` field will be an array of `Blob` objects
+    ensure: {
+      types: ['image/jpeg', 'image/png'] // allowed types of the file
+    },
+    put: {
+      addRandomSuffix: true
+    }
+  })
+})
diff --git a/src/runtime/components/FileUpload.vue b/src/runtime/components/FileUpload.vue
new file mode 100644
index 00000000..354bf713
--- /dev/null
+++ b/src/runtime/components/FileUpload.vue
@@ -0,0 +1,119 @@
+<script lang="ts">
+import type { AppConfig } from '@nuxt/schema'
+import type { UseFileDialogReturn } from '@vueuse/core'
+import theme from '#build/ui/file-upload'
+import type { ComponentConfig } from '../types/utils'
+
+type FileUpload = ComponentConfig<typeof theme, AppConfig, 'fileUpload'>
+
+export interface FileUploadProps<M extends boolean = false> {
+  /**
+   * The element or component this component should render as.
+   * @defaultValue 'div'
+   */
+  as?: any
+  id?: string
+  name?: string
+  required?: boolean
+  disabled?: boolean
+  multiple?: M & boolean
+  /**
+   * Specifies the allowed file types for the input. Provide a comma-separated list of MIME types or file extensions (e.g., "image/png,application/pdf,.jpg").
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/accept
+   * @defaultValue '*'
+   */
+  accept?: string
+  /**
+   * Reset the file input when the dialog is opened.
+   * @defaultValue false
+   */
+  reset?: boolean
+  /**
+   * Create a zone that allows the user to drop files onto it.
+   * @defaultValue false
+   */
+  dropzone?: boolean
+  class?: any
+  ui?: FileUpload['slots']
+}
+
+export interface FileUploadEmits<M extends boolean = false> {
+  (e: 'update:modelValue', value: M extends true ? File[] : File | null): void
+}
+
+export interface FileUploadSlots {
+  default(props: {
+    open: UseFileDialogReturn['open']
+    reset: UseFileDialogReturn['reset']
+    previewUrls: string[]
+  }): any
+}
+</script>
+
+<script setup lang="ts" generic="M extends boolean = false">
+import { ref, computed } from 'vue'
+import { Primitive } from 'reka-ui'
+import { useFileDialog, useDropZone } from '@vueuse/core'
+import { useAppConfig } from '#imports'
+import { useFormField } from '../composables/useFormField'
+
+import { tv } from '../utils/tv'
+
+defineOptions({ inheritAttrs: false })
+
+const props = withDefaults(defineProps<FileUploadProps<M>>(), {
+  accept: '*'
+})
+defineEmits<FileUploadEmits<M>>()
+defineSlots<FileUploadSlots>()
+
+const modelValue = defineModel<(M extends true ? File[] : File) | null>()
+
+const appConfig = useAppConfig() as FileUpload['AppConfig']
+
+const { emitFormInput, emitFormChange, id, name, disabled, ariaAttrs } = useFormField<FileUploadProps>(props, { deferInputValidation: true })
+
+// eslint-disable-next-line vue/no-dupe-keys
+const ui = computed(() => tv({ extend: tv(theme), ...(appConfig.ui?.fileUpload || {}) })({
+
+}))
+
+const inputRef = ref<HTMLInputElement>()
+
+const { files, open, reset, onCancel, onChange } = useFileDialog({
+  multiple: props.multiple,
+  accept: props.accept,
+  reset: props.reset,
+  input: inputRef.value
+})
+
+const previewUrls = computed(() => Array.from(files.value || []).map(file => URL.createObjectURL(file)))
+
+onChange((files) => {
+  console.log('files:', typeof files?.[0])
+  modelValue.value = props.multiple ? files : files?.[0]
+})
+
+onCancel(() => {
+  /** do something on cancel */
+})
+</script>
+
+<template>
+  <Primitive :as="as" :class="ui.root({ class: [props.ui?.root, props.class] })">
+    <slot :open="open" :reset="reset" :preview-urls="previewUrls" />
+
+    <input
+      :id="id"
+      ref="inputRef"
+      type="file"
+      :name="name"
+      :accept="accept"
+      :multiple="multiple"
+      :required="required"
+      :disabled="disabled"
+      hidden
+      v-bind="{ ...$attrs, ...ariaAttrs }"
+    >
+  </Primitive>
+</template>
diff --git a/src/runtime/types/index.ts b/src/runtime/types/index.ts
index f413b71c..bb9f0951 100644
--- a/src/runtime/types/index.ts
+++ b/src/runtime/types/index.ts
@@ -20,6 +20,7 @@ export * from '../components/Container.vue'
 export * from '../components/ContextMenu.vue'
 export * from '../components/Drawer.vue'
 export * from '../components/DropdownMenu.vue'
+export * from '../components/FileUpload.vue'
 export * from '../components/Form.vue'
 export * from '../components/FormField.vue'
 export * from '../components/Icon.vue'
diff --git a/src/theme/file-upload.ts b/src/theme/file-upload.ts
new file mode 100644
index 00000000..ab5a7066
--- /dev/null
+++ b/src/theme/file-upload.ts
@@ -0,0 +1,5 @@
+export default {
+  slots: {
+    root: ''
+  }
+}
diff --git a/src/theme/index.ts b/src/theme/index.ts
index e03aecd3..3958378c 100644
--- a/src/theme/index.ts
+++ b/src/theme/index.ts
@@ -19,6 +19,7 @@ export { default as container } from './container'
 export { default as contextMenu } from './context-menu'
 export { default as drawer } from './drawer'
 export { default as dropdownMenu } from './dropdown-menu'
+export { default as fileUpload } from './file-upload'
 export { default as form } from './form'
 export { default as formField } from './form-field'
 export { default as input } from './input'
diff --git a/test/components/FileUpload.spec.ts b/test/components/FileUpload.spec.ts
new file mode 100644
index 00000000..0e8b60c1
--- /dev/null
+++ b/test/components/FileUpload.spec.ts
@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest'
+import FileUpload from '../../src/runtime/components/FileUpload.vue'
+import type { FileUploadProps, FileUploadSlots } from '../../src/runtime/components/FileUpload.vue'
+import ComponentRender from '../component-render'
+
+describe('FileUpload', () => {
+  it.each([
+    // Props
+    ['with as', { props: { as: 'section' } }],
+    ['with class', { props: { class: '' } }],
+    ['with ui', { props: { ui: {} } }],
+    // Slots
+    ['with default slot', { slots: { default: () => 'Default slot' } }]
+  ])('renders %s correctly', async (nameOrHtml: string, options: { props?: FileUploadProps, slots?: Partial<FileUploadSlots> }) => {
+    const html = await ComponentRender(nameOrHtml, options, FileUpload)
+    expect(html).toMatchSnapshot()
+  })
+})