# File Upload **A file picker with drag and drop support, file lists, and validation hooks.** **Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/FileUpload) · [Zag.js Docs](https://zagjs.com/components/react/file-upload) **FileUpload.html** ```html Attachments
Drag files here or choose from your device
Images and PDFs up to 5 files.
Choose files Accepted/rejected files only ever exist as browser File objects, so the item markup is authored once as a ui:template and cloned/populated client-side per file.
No files selected yet. ``` **FileUpload.ts** ```ts import { mountAll } from 'fluid-primitives'; import { FileUpload } from 'fluid-primitives/file-upload'; mountAll('fileUpload', ({ props }) => { const fileUpload = new FileUpload(props); fileUpload.init(); return fileUpload; }); ``` ## Features - Supports button-triggered file selection and drag-and-drop uploads - Works with the `Field` primitive for form labels, descriptions, and validation - Supports accepted file types, file count limits, size limits, and directory selection - Exposes accepted and rejected files through the client-side API - Supports clearing files and deleting individual accepted files - Lets already-persisted files sit in the same list as newly-picked ones, so an edit form needs only one file list - Renders accepted/rejected file items from a Fluid-authored `itemTemplate`, since the actual `File` objects only ever exist in the browser - optionally a completely separate one for rejected items - Supports multiple preview variants per item, for example an image preview with a generic file-extension fallback - Exports `fileValue()`, the identity `FileUpload` stamps onto every rendered item's `data-value`, so userland code can resolve a clicked/found item back to the real `File` it represents - Replaces TYPO3's `f:form.upload` and integrates with Extbase's `#[FileUpload]` attribute out of the box ## Installation ```bash typo3 ui:add file-upload ``` Or copy the files manually from GitHub (https://github.com/jramke/fluid-primitives.com/tree/main/packages/docs/Resources/Private/Registry/FileUpload) into your project. Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md). ## Examples ### With Field Use file upload inside `Field` for form semantics and validation messaging. **FileUpload.html** ```html Resume
Upload your resume
PDF only, one file maximum.
Choose PDF
No files selected yet. We use this for your application review. ``` ### Accepted and Rejected Files Accepted and rejected files only ever exist as browser `File` objects, so they can never be part of the server-rendered markup. The `item` part is instead authored once inside an `itemTemplate` part inside `ui:fileUpload.root`, and the primitive clones/populates it for every accepted or rejected file - the same [`ui:template`](/docs/core-concepts/hydration.md) pattern the Combobox uses for asynchronously loaded results, just wrapped in a part so neither the stencil's internal name nor its `context` argument are something you need to type yourself. Rejected items use the `itemError` part to show why they were rejected, and can use an entirely different template (via `itemTemplate`'s `type` prop, see [Custom Item Layout](#custom-item-layout) below) when a rejected file shouldn't look like an accepted one at all. **FileUpload.html** ```html Portfolio Images
Drop up to two images
Large files will appear in a rejected list below.
Select images
One item template shared by both file lists below - the same markup renders an accepted or a rejected item, styled by its `data-type` attribute.
Accepted files
No files selected yet.
Rejected files
No rejected files.
``` ### Preview Variants Declare multiple `itemPreview` parts inside the item template, each with a `match` MIME type pattern (e.g. `image/*`). The primitive shows the first matching variant for a given file and hides the rest, which makes an image preview plus a generic fallback icon possible without a custom render callback. **FileUpload.html** ```html Attachments
Drag files here or choose from your device
Images and PDFs up to 5 files.
Choose files Accepted/rejected files only ever exist as browser File objects, so the item markup is authored once as a ui:template and cloned/populated client-side per file.
No files selected yet. ``` ### Translations `FileUpload` translates three labels: `dropzone` (the dropzone's `aria-label`), `itemPreview` (an accepted item's preview `alt` text), and `deleteFile` (an item's delete button `aria-label`). The last two are functions in zag-js (`(file: File) => string`), since they interpolate the file's name - but Fluid has no callbacks to hand over, and the `File` only exists in the browser anyway. So they're translated as plain strings containing a literal `%fileName%` placeholder, which the primitive substitutes with the real file name client-side: ```html ``` Use `%fileName%`, not `{fileName}` - Fluid's own inline array/object syntax already treats a bare `{...}` inside a string as a nested variable expression, so a curly-brace placeholder would silently get stripped from an override written this way. Omit `itemPreview`/`deleteFile` to keep the built-in translation, or set an entry to `{false}` to omit that `aria-label`/`alt` entirely. Per-locale overrides can also live in your own `locallang.xlf` and be read with `f:translate` instead. ### Directory Upload Enable directory selection in browsers that support `webkitdirectory`. **FileUpload.html** ```html Asset Folder
Select a directory
Useful for importing grouped assets or media folders.
Choose folder
No files selected yet. ``` ### Custom Item Layout Nothing about `itemTemplate` requires reusing the default part layout - author whatever markup you want inside it, drop parts you don't need (here, `itemSizeText` is left out entirely), and read the client-side API directly for anything that isn't a part at all, like a running "x / 5 files selected" count. Rejected items can use a second `itemTemplate`, given `type="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FileUploadItemType::Rejected')}"`, instead of reusing the accepted one - handy when a rejected file should look nothing like an accepted one, e.g. no preview at all. `FileUpload` falls back to the accepted `itemTemplate` for rejected items when no dedicated rejected one is given, so this is opt-in. The counter is plain userland JS: a `ui:ref` written directly in the root's slot content (`context="fileUpload"`, since it isn't part of the primitive's own template) is read back via `FileUpload`'s own `getElement()`, in a small subclass that updates it after every render. Item-level data with no corresponding part works the same way, but each rendered item first has to be found again. `itemModifiedDate` is a plain `ui:ref` inside the item template - `context="fileUpload"` is required here too (and not optional the way it might look from the counter above): ambient `ui:ref` resolution only reliably works for a primitive's own template body, or for hand-authored content with no other part rendered as a sibling first - `itemModifiedDate` sits right next to `itemPreview`/`fileName`, so it needs the explicit argument. The subclass's `render()` override then re-finds every rendered `item` via `getElements('item')`, reads each one's own `itemModifiedDate` child with `getElement('itemModifiedDate', itemEl)` - passing that specific item as the scope is what lets one `getElement()` call resolve correctly per file, the same way it already does for any other item-level part - matches its `data-value` back to a `File` via the exported `fileValue()` helper (the exact identity `FileUpload` itself stamps onto that attribute), and fills in the date. The same pattern works for any other per-item data a template needs. **FileUpload.html** ```html
Event Photos
0 / 5 files selected
Drop photos here or choose from your device
Up to 5 images. File size is intentionally not shown here.
Choose photos Accepted items get their own compact layout - a larger preview, a bold name and a text "Remove" trigger instead of the default icon button, and deliberately no file size. `itemModifiedDate` has no corresponding part anywhere in FileUpload - it's a plain ui:ref, populated entirely from userland JS (see CustomLayout.entry.ts), to test whether a consumer can show item-level data the primitive itself knows nothing about.
Remove Rejected items use a completely different template - no preview at all, just the file name and why it was rejected - and are listed in their own group below the accepted photos.
Dismiss
No photos selected yet.
Rejected
Nothing was rejected.
``` **CustomLayout.entry.ts** ```ts import { mount } from 'fluid-primitives'; import { FileUpload, fileValue } from 'fluid-primitives/file-upload'; function findFileByValue(files: File[], value: string): File | undefined { return files.find(file => fileValue(file) === value); } class FileUploadWithCounter extends FileUpload { render() { super.render(); this.updateFilesCounter(); this.updateItemModifiedDates(); } private updateFilesCounter() { const counterEl = this.getElement('filesCounter'); if (!counterEl) return; counterEl.textContent = `${this.api.acceptedFiles.length} / ${this.machine.prop('maxFiles')} files selected`; } /** * `itemModifiedDate` isn't a part FileUpload knows about at all - it's a plain ui:ref inside * the item template (see CustomLayout.html), populated entirely here. render() already reruns * on every accepted/rejected-files change (see Component.init()), which is also exactly when * new item clones need this filled in, so no separate wiring is needed beyond this loop. * getElement(part, itemEl) - scoped to one specific item - finds it despite there being one * per rendered file: Template's clone-time restamping (see ComponentHydrator.restampValue()) * gives every ref'd element with an id a unique one per file, the same way itemName/ * itemSizeText/itemPreview already get theirs, so no special handling is needed here either. */ private updateItemModifiedDates() { this.getElements('item').forEach(itemEl => { const dateEl = this.getElement('itemModifiedDate', itemEl); const value = itemEl.dataset.value; if (!dateEl || !value) return; const file = findFileByValue(this.api.acceptedFiles, value); if (!file) return; dateEl.textContent = `Modified ${new Date(file.lastModified).toLocaleDateString()}`; }); } } mount('fileUpload', 'custom-layout', ({ props }) => { const fileUpload = new FileUploadWithCounter(props); fileUpload.init(); return fileUpload; }); ``` ### Confirm File Deletion `itemDeleteTrigger` always deletes immediately once clicked - there's no built-in confirmation step, since what "confirm" means (a dialog, an undo toast, nothing) is entirely up to the consumer. This example pairs `FileUpload` with [`Dialog`](/docs/components/dialog.md) to ask before a file is actually removed: both are mounted as independent, hydration-controlled instances (`controlled="{true}"` + a fixed `rootId`, the same pattern [Combobox's custom filter example](/docs/components/combobox.md#custom-filter-api) uses), and a capturing-phase click listener on the item group intercepts the delete trigger's own click before it reaches FileUpload's built-in handler - `event.stopImmediatePropagation()` keeps the immediate delete from ever running. The file itself is recovered from the clicked item's `data-value` via the exported `fileValue()` helper (see [Custom Item Layout](#custom-item-layout) above), and only deleted (via `api.deleteFile()`) once the dialog is confirmed. Delegation is needed here because FileUpload re-clones its item markup on every accepted/rejected-files change, so there's no stable per-item element to attach a listener to directly. **FileUpload.html** ```html Documents
Drop documents here or choose from your device
Removing a file asks for confirmation first.
Choose files
No documents selected yet. A second, independently-controlled Dialog instance, opened programmatically from the entry file below instead of its own ui:dialog.trigger - clicking an item's delete button never deletes immediately, it opens this confirmation first. Remove file? This file will be removed from the upload. This can't be undone. Cancel ``` **FileUpload.ts** ```ts import { mountAll } from 'fluid-primitives'; import { FileUpload } from 'fluid-primitives/file-upload'; mountAll('fileUpload', ({ props }) => { const fileUpload = new FileUpload(props); fileUpload.init(); return fileUpload; }); ``` ## Using with Extbase `FileUpload` produces a plain, native `` under the hood, so it works with Extbase's [`#[FileUpload]` property attribute](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/Extbase/Domain/FileUpload.html) without any special controller code - it replaces `f:form.upload` one-to-one. ```php false, 'maxFiles' => 1, 'fileSize' => ['minimum' => '10K', 'maximum' => '2M'], 'mimeType' => ['allowedMimeTypes' => ['image/jpeg', 'image/png']], 'fileExtension' => ['allowedFileExtensions' => ['jpg', 'jpeg', 'png']], ], uploadFolder: '1:/user_upload/conference_logos/', )] protected ?FileReference $logo = null; /** * @var ObjectStorage */ #[FileUpload( validation: [ 'fileSize' => ['minimum' => '10K', 'maximum' => '10M'], 'mimeType' => ['allowedMimeTypes' => ['image/jpeg', 'image/png']], 'fileExtension' => ['allowedFileExtensions' => ['jpg', 'jpeg', 'png']], ], uploadFolder: '1:/user_upload/conference_impressions/', )] protected ObjectStorage $impressions; // constructor, initializeObject(), getters and setters... } ``` Use `ui:form.root`, and set `maxFiles` on `FileUpload` to match the property's cardinality - `1` for a single `FileReference`, greater than `1` for an `ObjectStorage`. For a multi-file property, write the `[]` suffix on `name` yourself, the same way you would for a [`CheckboxGroup`](/docs/components/checkbox-group.md) field bound to an array property - the primitive never appends it for you: ```html Logo Choose logo No logo selected yet. Impressions Choose images No images selected yet. ``` No `enctype` is needed on the form: `Form` never submits natively - it always posts a `FormData` body via `fetch` (see the [Forms guide](/docs/core-concepts/forms.md)), and `fetch` always sends a `FormData` body as `multipart/form-data` regardless of any `enctype` attribute, since it isn't reading the `
` element at all. ### Editing: Mixing Already-Uploaded Files With New Ones `FileUpload`'s own file list only ever holds files newly picked in the browser - it has no concept of an already-persisted `FileReference` from a previous request. For an edit form, render existing files as ordinary `item`s directly inside `ui:fileUpload.itemGroup`, alongside the newly-picked ones, instead of showing them in a second, separate list. Give each one `type="existing"` and pair its delete trigger with `ui:fileUploadDeleteCheckbox`, which renders TYPO3's HMAC-signed `@delete` token so Extbase removes the file reference on submit: Existing items still sit inside the same `itemTemplate`-driven `itemGroup` as newly-picked files (see [Accepted and Rejected Files](#accepted-and-rejected-files) above), so don't drop the item template when adding them - without it, the `itemGroup` renders the existing files fine, but selecting a _new_ file has nothing to clone and populate, and throws: ```html Impressions Choose images
{fileReference.originalResource.name}
No images selected yet. ``` Clicking that delete trigger checks the sibling checkbox and hides the item immediately, exactly like removing a newly-picked file - the actual `FileReference` is only deleted once the form is submitted. The checkbox must be a sibling of `fileDeleteTrigger`, never nested inside it: a native `