# File Upload URL: https://ark-ui.com/docs/components/file-upload Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/file-upload.mdx A component that is used to upload multiple files. --- ## Anatomy To set up the file upload component correctly, you'll need to understand its anatomy and how we name its parts. > Each part includes a `data-part` attribute to help identify them in the DOM. ## Examples Learn how to use the `FileUpload` component in your project. Let's take a look at the most basic example: **Example: basic** #### React ```tsx import { FileUpload } from '@ark-ui/react/file-upload' import { FileIcon } from 'lucide-react' export const Basic = () => { return ( File Upload Choose file(s) {({ acceptedFiles }) => acceptedFiles.map((file) => ( X )) } ) } ``` #### Solid ```tsx import { FileUpload } from '@ark-ui/solid/file-upload' import { For } from 'solid-js' export const Basic = () => ( File Upload Choose file(s) {(context) => ( {(file) => ( Any Icon X )} )} ) ``` #### Vue ```vue ``` #### Svelte ```svelte File Upload Choose file(s) {#snippet render(context)} {#each context().acceptedFiles as file (file.name)} X {/each} {/snippet} ``` ### Initial Files Use the `defaultAcceptedFiles` prop to set the initial files in the file upload component. **Example: initial-files** #### React ```tsx import { FileUpload } from '@ark-ui/react/file-upload' import { FileIcon } from 'lucide-react' export const InitialFiles = () => { return ( File Upload Choose file(s) {({ acceptedFiles }) => acceptedFiles.map((file) => ( )) } ) } ``` #### Solid ```tsx import { FileUpload } from '@ark-ui/solid/file-upload' import { For } from 'solid-js' export const InitialFiles = () => ( File Upload Choose file(s) {(context) => ( {(file) => (
📄
 )} )} ) ``` #### Vue ```vue ``` #### Svelte ```svelte File Upload Choose file(s) {#snippet render(context)} {#each context().acceptedFiles as file (file.name)}
📄
 {/each} {/snippet} ``` ### Clear Trigger Use the `ClearTrigger` component to provide users with a way to remove all uploaded files at once. This trigger will clear both accepted and rejected files from the upload component. **Example: clear-trigger** #### React ```tsx import { FileUpload } from '@ark-ui/react/file-upload' export const ClearTrigger = () => { return ( File Upload Choose file(s) Clear Files {({ acceptedFiles }) => acceptedFiles.map((file) => ( )) } ) } ``` #### Solid ```tsx import { FileUpload } from '@ark-ui/solid/file-upload' import { For } from 'solid-js' export const ClearTrigger = () => ( File Upload Choose file(s) Clear Files {(context) => ( {(file) => ( )} )} ) ``` #### Vue ```vue ``` #### Svelte ```svelte File Upload Drag your file(s) here Choose file(s) {#snippet render(context)} {#if context().acceptedFiles.length > 0} {/if} {/snippet} {#snippet render(context)} {#each context().acceptedFiles as file (file.name)} X {/each} {/snippet} ``` ### Drag & Drop Use the `Dropzone` component to enable drag-and-drop functionality. The dropzone provides adds a `data-dragging` attribute while dragging for styling purposes. **Example: drag-and-drop** #### React ```tsx import { FileUpload } from '@ark-ui/react/file-upload' export const DragAndDrop = () => { return ( Drag and drop your images here {({ acceptedFiles }) => acceptedFiles.map((file) => ( )) } ) } ``` #### Solid ```tsx import { FileUpload } from '@ark-ui/solid/file-upload' import { For } from 'solid-js' export const DragAndDrop = () => ( Drag and drop your images here {(fileUpload) => ( {(file) => ( )} )} ) ``` #### Vue ```vue ``` #### Svelte ```svelte Drag and drop your images here {#snippet render(fileUpload)} {#each fileUpload().acceptedFiles as file (file.name)} {/each} {/snippet} ``` ### Directory Upload Use the `directory` prop to allow users to upload entire folders. This enables selecting multiple files from a directory structure while preserving the folder hierarchy. **Example: directory-upload** #### React ```tsx import { FileUpload } from '@ark-ui/react/file-upload' export const DirectoryUpload = () => { return ( Upload Folder {({ acceptedFiles }) => acceptedFiles.map((file) => ( {file.webkitRelativePath ?? file.name} )) } ) } ``` #### Solid ```tsx import { FileUpload } from '@ark-ui/solid/file-upload' import { For } from 'solid-js' export const DirectoryUpload = () => ( Upload Folder {(fileUpload) => ( {(file) => ( {file.webkitRelativePath ?? file.name} )} )} ) ``` #### Vue ```vue ``` #### Svelte ```svelte Upload Folder {#snippet render(fileUpload)} {#each fileUpload().acceptedFiles as file (file.name)} {file.webkitRelativePath ?? file.name} {/each} {/snippet} ``` The `file.webkitRelativePath` property contains the full path of each file within the uploaded directory, allowing you to display the folder structure or process files based on their location. > **Important**: When uploading directories with many files, set `maxFiles` to a higher value (e.g., `maxFiles={100}`) > or remove the limit entirely to prevent files from being rejected due to the default file count restriction. ### Accepted File Types Use the `accept` prop to restrict the file types that can be uploaded. This prop accepts MIME types (e.g., `image/png`, `image/jpeg`) or file extensions (e.g., `.pdf`, `.txt`). When users attempt to upload files that don't match the accepted types, these files will be automatically rejected and appear in the `rejectedFiles` array with a `FILE_INVALID_TYPE` error code. **Example: accepted-file-types** #### React ```tsx import { FileUpload } from '@ark-ui/react/file-upload' export const AcceptedFileTypes = () => { return ( File Upload (PNG and JPEG only) Drop your files here Select Files {({ acceptedFiles }) => acceptedFiles.map((file) => ( Remove )) } {({ rejectedFiles }) => rejectedFiles.map((fileRejection) => (
{fileRejection.errors.map((error) => (
{error}
))}
)) } ) } ``` #### Solid ```tsx import { FileUpload } from '@ark-ui/solid/file-upload' import { For } from 'solid-js' export const AcceptedFileTypes = () => ( File Upload (PNG and JPEG only) Drop your files here Select Files {(context) => ( {(file) => ( Remove )} )} {(context) => ( {(fileRejection) => (
{(error) =>
{error}
}
)} )} ) ``` #### Vue ```vue ``` #### Svelte ```svelte File Upload (PNG and JPEG only) Drop your files here Select Files {#snippet render(context)} {#each context().acceptedFiles as file (file.name)} Remove {/each} {/snippet} {#snippet render(context)} {#each context().rejectedFiles as fileRejection (fileRejection.file.name)}
{#each fileRejection.errors as error}
{error}
{/each}
{/each} {/snippet} ``` ### Error Handling The `FileUpload` component provides comprehensive validation and error handling capabilities. You can set various constraints and handle different types of validation errors: **Built-in Validation Props:** - `maxFiles` - Maximum number of files allowed - `maxFileSize` - Maximum file size in bytes - `minFileSize` - Minimum file size in bytes - `accept` - Allowed MIME types or file extensions **Built-in Error Types:** - `TOO_MANY_FILES` - Exceeds maxFiles limit - `FILE_INVALID_TYPE` - File type not in accept list - `FILE_TOO_LARGE` - File size exceeds maxFileSize - `FILE_TOO_SMALL` - File size below minFileSize - `FILE_INVALID` - Generic validation failure - `FILE_EXISTS` - Duplicate file detected **Example: error-handling** #### React ```tsx import { FileUpload, type FileUploadFileError } from '@ark-ui/react/file-upload' const errorMessages: Record = { TOO_MANY_FILES: '📊 Too many files selected (max 3 allowed)', FILE_INVALID_TYPE: '🚫 Invalid file type (only images and PDFs allowed)', FILE_TOO_LARGE: '📏 File too large (max 1MB)', FILE_TOO_SMALL: '📐 File too small (min 1KB)', FILE_INVALID: '⚠️ Invalid file', FILE_EXISTS: '🔄 File already exists', } export const ErrorHandling = () => { return ( File Upload with Validation Select Files {/* Accepted Files Section */}

✅ Accepted Files

{({ acceptedFiles }) => acceptedFiles.length === 0 ? (
No files uploaded yet
) : ( acceptedFiles.map((file) => (
PDF
 Remove )) ) }
{/* Rejected Files Section */}

❌ Rejected Files

{({ rejectedFiles }) => rejectedFiles.length === 0 ? (
No rejected files
) : ( rejectedFiles.map((fileRejection) => (
Validation Errors: {fileRejection.errors.map((error, index) => (
{errorMessages[error as FileUploadFileError] || `❓ ${error}`}
))}
)) ) }
) } ``` #### Solid ```tsx import { FileUpload, type FileUploadFileError } from '@ark-ui/solid/file-upload' import { For } from 'solid-js' const errorMessages: Record = { TOO_MANY_FILES: '📊 Too many files selected (max 3 allowed)', FILE_INVALID_TYPE: '🚫 Invalid file type (only images and PDFs allowed)', FILE_TOO_LARGE: '📏 File too large (max 1MB)', FILE_TOO_SMALL: '📐 File too small (min 1KB)', FILE_INVALID: '⚠️ Invalid file', FILE_EXISTS: '🔄 File already exists', } export const ErrorHandling = () => ( File Upload with Validation Select Files {/* Accepted Files Section */}

✅ Accepted Files

{(fileUpload) => fileUpload().acceptedFiles.length === 0 ? (
No files uploaded yet
) : ( {(file) => (
PDF
 Remove )} ) }
{/* Rejected Files Section */}

❌ Rejected Files

{(fileUpload) => fileUpload().rejectedFiles.length === 0 ? (
No rejected files
) : ( {(fileRejection) => (
Validation Errors: {(error) =>
{errorMessages[error] || `❓ ${error}`}
}
)} ) }
) ``` #### Vue ```vue ``` #### Svelte ```svelte File Upload with Validation Select Files

✅ Accepted Files

{#snippet render(fileUpload)} {#if fileUpload().acceptedFiles.length === 0}
No files uploaded yet
{:else} {#each fileUpload().acceptedFiles as file (file.name)}
PDF
 Remove {/each} {/if} {/snippet}

❌ Rejected Files

{#snippet render(fileUpload)} {#if fileUpload().rejectedFiles.length === 0}
No rejected files
{:else} {#each fileUpload().rejectedFiles as fileRejection (fileRejection.file.name)}
Validation Errors: {#each fileRejection.errors as error}
{errorMessages[error] || `❓ ${error}`}
{/each}
{/each} {/if} {/snippet}
``` ### File Transformations Use the `transformFiles` prop to process files before they're added to the accepted files list. This is useful for file compression, format conversion, or adding metadata. **Common transformation use cases:** - **Image compression**: Use `image-conversion`, `browser-image-compression`, or similar libraries - **Format conversion**: Convert files to different formats (e.g., HEIC to JPEG) - **Metadata extraction**: Add EXIF data or other file information - **File validation**: Perform additional checks beyond basic validation - **Resizing**: Automatically resize images to specific dimensions **Example: file-transformations** #### React ```tsx import { FileUpload } from '@ark-ui/react/file-upload' import { compressAccurately } from 'image-conversion' export const FileTransformations = () => { const transformFiles = async (files: File[]) => { return Promise.all( files.map(async (file) => { if (file.type.startsWith('image/')) { try { // Compress image to ~200KB const blob = await compressAccurately(file, 200) return new File([blob], file.name, { type: blob.type }) } catch (error) { console.error('Compression failed for:', file.name, error) return file } } return file // Return non-image files as-is }), ) } return ( File Upload with Compression Choose Images {({ acceptedFiles }) => acceptedFiles.map((file) => ( Remove )) } ) } ``` #### Solid ```tsx import { FileUpload } from '@ark-ui/solid/file-upload' import { compressAccurately } from 'image-conversion' import { For } from 'solid-js' export const FileTransformations = () => { const transformFiles = async (files: File[]) => { return Promise.all( files.map(async (file) => { if (file.type.startsWith('image/')) { try { const blob = await compressAccurately(file, 200) return new File([blob], file.name, { type: blob.type }) } catch (error) { console.error('Compression failed for:', file.name, error) return file } } return file }), ) } return ( File Upload with Compression Choose Images {(fileUpload) => ( {(file) => ( Remove )} )} ) } ``` #### Vue ```vue ``` #### Svelte ```svelte File Upload with Compression Choose Images {#snippet render(fileUpload)} {#each fileUpload().acceptedFiles as file (file.name)} Remove {/each} {/snippet} ``` ### Custom Validation Use the `validate` prop to implement custom validation logic beyond the built-in constraints. **Example: validation** #### React ```tsx import { FileUpload } from '@ark-ui/react/file-upload' import { FileIcon } from 'lucide-react' export const WithValidation = () => { return ( { if (file.name.length > 20) return ['FILE_NAME_TOO_LONG'] return null }} > Choose file(s) {({ acceptedFiles }) => acceptedFiles.map((file) => ( X )) } ) } ``` #### Solid ```tsx import { FileUpload } from '@ark-ui/solid/file-upload' import { FileIcon } from 'lucide-solid' import { For } from 'solid-js' export const WithValidation = () => { return ( { if (file.name.length > 20) return ['FILE_NAME_TOO_LONG'] return null }} > Choose file(s) {(context) => ( {(file) => ( X )} )} ) } ``` #### Vue ```vue ``` #### Svelte ```svelte Choose file(s) {#snippet render(context)} {#each context().acceptedFiles as file (file.name)} X {/each} {/snippet} {#snippet render(context)} {#if context().rejectedFiles.length > 0}

Rejected Files:

{#each context().rejectedFiles as rejectedFile}

{rejectedFile.file.name} - {rejectedFile.errors[0]}

{/each}
{/if} {/snippet} ``` ### Field Here's an example of how to use the `FileUpload` component with the `Field` component to provide a error and helper text. **Example: with-field** #### React ```tsx import { Field } from '@ark-ui/react/field' import { FileUpload } from '@ark-ui/react/file-upload' export const WithField = (props: Field.RootProps) => ( Label Select Additional Info Error Info ) ``` #### Solid ```tsx import { Field } from '@ark-ui/solid/field' import { FileUpload } from '@ark-ui/solid/file-upload' export const WithField = (props: Field.RootProps) => ( Label Select Additional Info Error Info ) ``` #### Vue ```vue ``` #### Svelte ```svelte Label Select Additional Info Error Info ``` ### Root Provider Use the `useFileUpload` hook to create the file upload store and pass it to the `RootProvider` component. This allows you to have maximum control over the file upload programmatically. > If you're using the `RootProvider` component, you don't need to use the `Root` component. **Example: root-provider** #### React ```tsx import { FileUpload, useFileUpload } from '@ark-ui/react/file-upload' import { FileIcon } from 'lucide-react' export const RootProvider = () => { const fileUpload = useFileUpload({ maxFiles: 5 }) return ( <> File Upload Drag your file(s) here Choose file(s) {({ acceptedFiles }) => acceptedFiles.map((file) => ( X )) } ) } ``` #### Solid ```tsx import { FileUpload, useFileUpload } from '@ark-ui/solid/file-upload' import { For } from 'solid-js' export const RootProvider = () => { const fileUpload = useFileUpload({ maxFiles: 5 }) return ( <> File Upload Drag your file(s)here Choose file(s) {(context) => ( {(file) => ( Any Icon X )} )} ) } ``` #### Vue ```vue ``` #### Svelte ```svelte
File Upload Drag your file(s) here Choose file(s) {#snippet render(context)} {#each context().acceptedFiles as file (file.name)} X {/each} {/snippet}
``` ### Pasting Files Use the `setClipboardFiles` method to enable pasting images directly from the clipboard. > You can access the `fileUpload` store from `FileUpload.Context` as well. **Example: with-paste** #### React ```tsx import { FileUpload, useFileUpload } from '@ark-ui/react/file-upload' import { XIcon } from 'lucide-react' export const WithPaste = () => { const fileUpload = useFileUpload({ maxFiles: 3, accept: 'image/*' }) return ( File Upload with Paste {#each fileUpload().acceptedFiles as file (file.name)} X {/each} ``` ## Guides ### File Previews The `FileUpload` component provides flexible preview options for different file types. Use `ItemPreview` with type matching to show appropriate previews based on file format. **Preview Types:** - `type="image/*"`: Shows image thumbnails using `ItemPreviewImage` - `type="video/*"`: For video file previews - `type="application/pdf"`: For PDF files - `type=".*"`: Generic fallback for any file type ```tsx ``` **File Metadata Display:** - `ItemName` - Shows the file name - `ItemSizeText` - Shows formatted file size (e.g., "2.5 MB") ### Disable dropzone To disable drag-and-drop functionality, set the `allowDrop` prop to `false`. ```tsx {/* ... */} ``` ### Prevent document drop By default, when the dropzone is active, we prevent accidental navigation when files are dropped outside the dropzone. To prevent this behavior, set the `preventDocumentDrop` prop to `false`. ```tsx {/* ... */} ``` ### Prevent double open When you want to delegate clicking to the trigger and remove the dropzone from the tab order, you can use the `disableClick` prop. This prevents the the file picker from opening twice. ```tsx Choose Files Drag files here ``` ## API Reference ### Props **Component API Reference** #### React **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `accept` | `Record | FileMimeType | FileMimeType[]` | No | The accept file types | | `acceptedFiles` | `File[]` | No | The controlled accepted files | | `allowDrop` | `boolean` | No | Whether to allow drag and drop in the dropzone element | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `capture` | `'user' | 'environment'` | No | The default camera to use when capturing media | | `defaultAcceptedFiles` | `File[]` | No | The default accepted files when rendered. Use when you don't need to control the accepted files of the input. | | `directory` | `boolean` | No | Whether to accept directories, only works in webkit browsers | | `disabled` | `boolean` | No | Whether the file input is disabled | | `ids` | `Partial<{ root: string dropzone: string hiddenInput: string trigger: string label: string item: (id: string) => string itemName: (id: string) => string itemSizeText: (id: string) => string itemPreview: (id: string) => string }>` | No | The ids of the elements. Useful for composition. | | `invalid` | `boolean` | No | Whether the file input is invalid | | `locale` | `string` | No | The current locale. Based on the BCP 47 definition. | | `maxFiles` | `number` | No | The maximum number of files | | `maxFileSize` | `number` | No | The maximum file size in bytes | | `minFileSize` | `number` | No | The minimum file size in bytes | | `name` | `string` | No | The name of the underlying file input | | `onFileAccept` | `(details: FileAcceptDetails) => void` | No | Function called when the file is accepted | | `onFileChange` | `(details: FileChangeDetails) => void` | No | Function called when the value changes, whether accepted or rejected | | `onFileReject` | `(details: FileRejectDetails) => void` | No | Function called when the file is rejected | | `preventDocumentDrop` | `boolean` | No | Whether to prevent the drop event on the document | | `required` | `boolean` | No | Whether the file input is required | | `transformFiles` | `(files: File[]) => Promise` | No | Function to transform the accepted files to apply transformations | | `translations` | `IntlTranslations` | No | The localized messages to use. | | `validate` | `(file: File, details: FileValidateDetails) => FileError[] | null` | No | Function to validate a file | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-dragging]` | Present when in the dragging state | **ClearTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ClearTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | clear-trigger | | `[data-disabled]` | Present when disabled | **Dropzone Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disableClick` | `boolean` | No | Whether to disable the click event on the dropzone | **Dropzone Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | dropzone | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-dragging]` | Present when in the dragging state | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemDeleteTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemDeleteTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-delete-trigger | | `[data-disabled]` | Present when disabled | **ItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-group | | `[data-disabled]` | Present when disabled | **ItemName Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemName Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-name | | `[data-disabled]` | Present when disabled | **ItemPreviewImage Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemPreviewImage Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-preview-image | | `[data-disabled]` | Present when disabled | **ItemPreview Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `type` | `string` | No | The file type to match against. Matches all file types by default. | **ItemPreview Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-preview | | `[data-disabled]` | Present when disabled | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `file` | `File` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item | | `[data-disabled]` | Present when disabled | **ItemSizeText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemSizeText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-size-text | | `[data-disabled]` | Present when disabled | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseFileUploadReturn` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | trigger | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | #### Solid **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `accept` | `Record | FileMimeType | FileMimeType[]` | No | The accept file types | | `acceptedFiles` | `File[]` | No | The controlled accepted files | | `allowDrop` | `boolean` | No | Whether to allow drag and drop in the dropzone element | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `capture` | `'user' | 'environment'` | No | The default camera to use when capturing media | | `defaultAcceptedFiles` | `File[]` | No | The default accepted files when rendered. Use when you don't need to control the accepted files of the input. | | `directory` | `boolean` | No | Whether to accept directories, only works in webkit browsers | | `disabled` | `boolean` | No | Whether the file input is disabled | | `ids` | `Partial<{ root: string dropzone: string hiddenInput: string trigger: string label: string item: (id: string) => string itemName: (id: string) => string itemSizeText: (id: string) => string itemPreview: (id: string) => string }>` | No | The ids of the elements. Useful for composition. | | `invalid` | `boolean` | No | Whether the file input is invalid | | `locale` | `string` | No | The current locale. Based on the BCP 47 definition. | | `maxFiles` | `number` | No | The maximum number of files | | `maxFileSize` | `number` | No | The maximum file size in bytes | | `minFileSize` | `number` | No | The minimum file size in bytes | | `name` | `string` | No | The name of the underlying file input | | `onFileAccept` | `(details: FileAcceptDetails) => void` | No | Function called when the file is accepted | | `onFileChange` | `(details: FileChangeDetails) => void` | No | Function called when the value changes, whether accepted or rejected | | `onFileReject` | `(details: FileRejectDetails) => void` | No | Function called when the file is rejected | | `preventDocumentDrop` | `boolean` | No | Whether to prevent the drop event on the document | | `required` | `boolean` | No | Whether the file input is required | | `transformFiles` | `(files: File[]) => Promise` | No | Function to transform the accepted files to apply transformations | | `translations` | `IntlTranslations` | No | The localized messages to use. | | `validate` | `(file: File, details: FileValidateDetails) => FileError[] | null` | No | Function to validate a file | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-dragging]` | Present when in the dragging state | **ClearTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ClearTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | clear-trigger | | `[data-disabled]` | Present when disabled | **Dropzone Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disableClick` | `boolean` | No | Whether to disable the click event on the dropzone | **Dropzone Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | dropzone | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-dragging]` | Present when in the dragging state | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemDeleteTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemDeleteTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-delete-trigger | | `[data-disabled]` | Present when disabled | **ItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'ul'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-group | | `[data-disabled]` | Present when disabled | **ItemName Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemName Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-name | | `[data-disabled]` | Present when disabled | **ItemPreviewImage Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'img'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemPreviewImage Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-preview-image | | `[data-disabled]` | Present when disabled | **ItemPreview Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `type` | `string` | No | The file type to match against. Matches all file types by default. | **ItemPreview Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-preview | | `[data-disabled]` | Present when disabled | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `file` | `File` | Yes | | | `asChild` | `(props: ParentProps<'li'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item | | `[data-disabled]` | Present when disabled | **ItemSizeText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemSizeText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-size-text | | `[data-disabled]` | Present when disabled | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseFileUploadReturn` | Yes | | | `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | trigger | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | #### Vue **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `accept` | `Record | FileMimeType | FileMimeType[]` | No | The accept file types | | `allowDrop` | `boolean` | No | Whether to allow drag and drop in the dropzone element | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `capture` | `'user' | 'environment'` | No | The default camera to use when capturing media | | `defaultAcceptedFiles` | `File[]` | No | The default accepted files | | `directory` | `boolean` | No | Whether to accept directories, only works in webkit browsers | | `disabled` | `boolean` | No | Whether the file input is disabled | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string dropzone: string hiddenInput: string trigger: string label: string item(id: string): string itemName(id: string): string itemSizeText(id: string): string itemPreview(id: string): string }>` | No | The ids of the elements. Useful for composition. | | `invalid` | `boolean` | No | Whether the file input is invalid | | `locale` | `string` | No | The current locale. Based on the BCP 47 definition. | | `maxFiles` | `number` | No | The maximum number of files | | `maxFileSize` | `number` | No | The maximum file size in bytes | | `minFileSize` | `number` | No | The minimum file size in bytes | | `name` | `string` | No | The name of the underlying file input | | `preventDocumentDrop` | `boolean` | No | Whether to prevent the drop event on the document | | `required` | `boolean` | No | Whether the file input is required | | `transformFiles` | `(files: File[]) => Promise` | No | Function to transform the files | | `translations` | `IntlTranslations` | No | The localized messages to use. | | `validate` | `(file: File, details: FileValidateDetails) => FileError[] | null` | No | Function to validate a file | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-dragging]` | Present when in the dragging state | **ClearTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ClearTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | clear-trigger | | `[data-disabled]` | Present when disabled | **Dropzone Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disableClick` | `boolean` | No | Whether to disable the click event on the dropzone | **Dropzone Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | dropzone | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-dragging]` | Present when in the dragging state | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemDeleteTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemDeleteTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-delete-trigger | | `[data-disabled]` | Present when disabled | **ItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-group | | `[data-disabled]` | Present when disabled | **ItemName Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemName Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-name | | `[data-disabled]` | Present when disabled | **ItemPreviewImage Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemPreviewImage Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-preview-image | | `[data-disabled]` | Present when disabled | **ItemPreview Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `type` | `string` | No | The file type to match against. Matches all file types by default. | **ItemPreview Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-preview | | `[data-disabled]` | Present when disabled | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `file` | `File` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item | | `[data-disabled]` | Present when disabled | **ItemSizeText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **ItemSizeText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-size-text | | `[data-disabled]` | Present when disabled | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `FileUploadApi` | Yes | | | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | trigger | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | #### Svelte **Root Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `accept` | `FileMimeType | Record | FileMimeType[]` | No | The accept file types | | `acceptedFiles` | `File[]` | No | The controlled accepted files | | `allowDrop` | `boolean` | No | Whether to allow drag and drop in the dropzone element | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `capture` | `'user' | 'environment'` | No | The default camera to use when capturing media | | `defaultAcceptedFiles` | `File[]` | No | The default accepted files when rendered. Use when you don't need to control the accepted files of the input. | | `directory` | `boolean` | No | Whether to accept directories, only works in webkit browsers | | `disabled` | `boolean` | No | Whether the file input is disabled | | `id` | `string` | No | The unique identifier of the machine. | | `ids` | `Partial<{ root: string dropzone: string hiddenInput: string trigger: string label: string item: (id: string) => string itemName: (id: string) => string itemSizeText: (id: string) => string itemPreview: (id: string) => string }>` | No | The ids of the elements. Useful for composition. | | `invalid` | `boolean` | No | Whether the file input is invalid | | `locale` | `string` | No | The current locale. Based on the BCP 47 definition. | | `maxFiles` | `number` | No | The maximum number of files | | `maxFileSize` | `number` | No | The maximum file size in bytes | | `minFileSize` | `number` | No | The minimum file size in bytes | | `name` | `string` | No | The name of the underlying file input | | `onFileAccept` | `(details: FileAcceptDetails) => void` | No | Function called when the file is accepted | | `onFileChange` | `(details: FileChangeDetails) => void` | No | Function called when the value changes, whether accepted or rejected | | `onFileReject` | `(details: FileRejectDetails) => void` | No | Function called when the file is rejected | | `preventDocumentDrop` | `boolean` | No | Whether to prevent the drop event on the document | | `ref` | `Element` | No | | | `required` | `boolean` | No | Whether the file input is required | | `transformFiles` | `(files: File[]) => Promise` | No | Function to transform the accepted files to apply transformations | | `translations` | `IntlTranslations` | No | The localized messages to use. | | `validate` | `(file: File, details: FileValidateDetails) => FileError[] | null` | No | Function to validate a file | **Root Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | root | | `[data-disabled]` | Present when disabled | | `[data-dragging]` | Present when in the dragging state | **ClearTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ClearTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | clear-trigger | | `[data-disabled]` | Present when disabled | **Context Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `render` | `Snippet<[UseFileUploadContext]>` | No | | **Dropzone Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `disableClick` | `boolean` | No | Whether to disable the click event on the dropzone | | `ref` | `Element` | No | | **Dropzone Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | dropzone | | `[data-invalid]` | Present when invalid | | `[data-disabled]` | Present when disabled | | `[data-dragging]` | Present when in the dragging state | **HiddenInput Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ItemDeleteTrigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ItemDeleteTrigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-delete-trigger | | `[data-disabled]` | Present when disabled | **ItemGroup Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ItemGroup Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-group | | `[data-disabled]` | Present when disabled | **ItemName Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ItemName Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-name | | `[data-disabled]` | Present when disabled | **ItemPreviewImage Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'img'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ItemPreviewImage Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-preview-image | | `[data-disabled]` | Present when disabled | **ItemPreview Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | | `type` | `string` | No | The file type to match against. Matches all file types by default. | **ItemPreview Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-preview | | `[data-disabled]` | Present when disabled | **Item Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `file` | `File` | Yes | | | `asChild` | `Snippet<[PropsFn<'li'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Item Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item | | `[data-disabled]` | Present when disabled | **ItemSizeText Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **ItemSizeText Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | item-size-text | | `[data-disabled]` | Present when disabled | **Label Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Label Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | label | | `[data-disabled]` | Present when disabled | **RootProvider Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `value` | `UseFileUploadReturn` | Yes | | | `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Props:** | Prop | Type | Required | Description | |------|------|----------|-------------| | `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. | | `ref` | `Element` | No | | **Trigger Data Attributes:** | Attribute | Value | |-----------|-------| | `[data-scope]` | file-upload | | `[data-part]` | trigger | | `[data-disabled]` | Present when disabled | | `[data-invalid]` | Present when invalid | ### Context These are the properties available when using `UfileUupload.Context`, `useUfileUuploadContext` hook or `useUfileUupload` hook. **API:** | Property | Type | Description | |----------|------|-------------| | `dragging` | `boolean` | Whether the user is dragging something over the root element | | `focused` | `boolean` | Whether the user is focused on the dropzone element | | `disabled` | `boolean` | Whether the file input is disabled | | `transforming` | `boolean` | Whether files are currently being transformed via `transformFiles` | | `openFilePicker` | `VoidFunction` | Function to open the file dialog | | `deleteFile` | `(file: File, type?: ItemType) => void` | Function to delete the file from the list | | `acceptedFiles` | `File[]` | The accepted files that have been dropped or selected | | `rejectedFiles` | `FileRejection[]` | The files that have been rejected | | `setFiles` | `(files: File[]) => void` | Sets the accepted files | | `clearFiles` | `VoidFunction` | Clears the accepted files | | `clearRejectedFiles` | `VoidFunction` | Clears the rejected files | | `getFileSize` | `(file: File) => string` | Returns the formatted file size (e.g. 1.2MB) | | `createFileUrl` | `(file: File, cb: (url: string) => void) => VoidFunction` | Returns the preview url of a file. Returns a function to revoke the url. | | `setClipboardFiles` | `(dt: DataTransfer) => boolean` | Sets the clipboard files Returns `true` if the clipboard data contains files, `false` otherwise. |