File Upload

A file picker with drag and drop support, file lists, and validation hooks.

Attachments

Drag files here or choose from your device

Images and PDFs up to 5 files.

No files selected yet.

<ui:fileUpload.root name="attachments[]" maxFiles="5" accept="image/*,.pdf">
    <ui:fileUpload.label>Attachments</ui:fileUpload.label>
    <ui:fileUpload.dropzone>
        <div class="grid gap-1">
            <div class="text-sm font-medium">Drag files here or choose from your device</div>
            <div class="text-muted-foreground text-sm">Images and PDFs up to 5 files.</div>
        </div>
        <ui:fileUpload.trigger>Choose files</ui:fileUpload.trigger>
    </ui:fileUpload.dropzone>

    <f:comment>
        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.
    </f:comment>
    <primitives:fileUpload.itemTemplate>
        <ui:fileUpload.fileItem>
            <ui:fileUpload.itemPreview match="image/*">
                <ui:fileUpload.itemPreviewImage />
            </ui:fileUpload.itemPreview>
            <ui:fileUpload.itemPreview match=".*">
                <ui:fileUpload.filePreviewFallback />
            </ui:fileUpload.itemPreview>

            <div class="grid min-w-0 flex-1 gap-0.5">
                <ui:fileUpload.fileName />
                <ui:fileUpload.fileMeta />
                <ui:fileUpload.fileError />
            </div>

            <ui:fileUpload.fileDeleteTrigger />
        </ui:fileUpload.fileItem>
    </primitives:fileUpload.itemTemplate>

    <ui:fileUpload.itemGroup>
        <ui:fileUpload.emptyState>No files selected yet.</ui:fileUpload.emptyState>
    </ui:fileUpload.itemGroup>
</ui:fileUpload.root>

Features

Button-triggered file selection and drag and drop
Accepted file types, file count limits, size limits and directory selection
Accepted and rejected files through the client-side API
Clear all files or delete a single one
Already-stored files and newly picked files in one list, for edit forms
Items authored in Fluid with an itemTemplate, plus a template of their own for rejected items
Preview variants per item, for example an image with a file-extension fallback
fileValue() maps a rendered item back to its File
Works with Field and with Extbase's #[FileUpload] attribute, as a drop-in for f:form.upload

Anatomy

<primitives:fileUpload.root>
    <primitives:fileUpload.label />
    <primitives:fileUpload.dropzone>
        <primitives:fileUpload.trigger />
    </primitives:fileUpload.dropzone>
    <primitives:fileUpload.hiddenInput />

    <primitives:fileUpload.itemTemplate>
        <primitives:fileUpload.item>
            <primitives:fileUpload.itemPreview match="image/*">
                <primitives:fileUpload.itemPreviewImage />
            </primitives:fileUpload.itemPreview>
            <primitives:fileUpload.itemPreview match=".*">
                <primitives:fileUpload.itemPreviewFallback />
            </primitives:fileUpload.itemPreview>
            <primitives:fileUpload.itemName />
            <primitives:fileUpload.itemSizeText />
            <primitives:fileUpload.itemError />
            <primitives:fileUpload.itemDeleteTrigger />
        </primitives:fileUpload.item>
    </primitives:fileUpload.itemTemplate>

    <f:comment>Optional - falls back to the itemTemplate above when omitted.</f:comment>
    <primitives:fileUpload.itemTemplate
        type="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FileUploadItemType::Rejected')}"
    >
        <primitives:fileUpload.item>
            <primitives:fileUpload.itemName />
            <primitives:fileUpload.itemError />
            <primitives:fileUpload.itemDeleteTrigger />
        </primitives:fileUpload.item>
    </primitives:fileUpload.itemTemplate>

    <primitives:fileUpload.itemGroup>
        <primitives:fileUpload.emptyState />
    </primitives:fileUpload.itemGroup>
    <primitives:fileUpload.clearTrigger />
</primitives:fileUpload.root>

Installation

typo3 ui:add fileUpload

Read more about installing Components and Primitives.

Examples

Use a file upload in a field

Wrap the file upload in a Field to add helper text and error text, and to mark it required.

Resume

Upload your resume

PDF only, one file maximum.

No files selected yet.

We use this for your application review.

<ui:field.root name="resume" required="{true}">
    <ui:fileUpload.root accept=".pdf">
        <ui:fileUpload.label>Resume</ui:fileUpload.label>
        <ui:fileUpload.dropzone>
            <div class="grid gap-1">
                <div class="text-sm font-medium">Upload your resume</div>
                <div class="text-muted-foreground text-sm">PDF only, one file maximum.</div>
            </div>
            <ui:fileUpload.trigger>Choose PDF</ui:fileUpload.trigger>
        </ui:fileUpload.dropzone>

        <primitives:fileUpload.itemTemplate>
            <ui:fileUpload.fileItem>
                <ui:fileUpload.itemPreview match="image/*">
                    <ui:fileUpload.itemPreviewImage />
                </ui:fileUpload.itemPreview>
                <ui:fileUpload.itemPreview match=".*">
                    <ui:fileUpload.filePreviewFallback />
                </ui:fileUpload.itemPreview>

                <div class="grid min-w-0 flex-1 gap-0.5">
                    <ui:fileUpload.fileName />
                    <ui:fileUpload.fileMeta />
                    <ui:fileUpload.fileError />
                </div>

                <ui:fileUpload.fileDeleteTrigger />
            </ui:fileUpload.fileItem>
        </primitives:fileUpload.itemTemplate>

        <ui:fileUpload.itemGroup>
            <ui:fileUpload.emptyState>No files selected yet.</ui:fileUpload.emptyState>
        </ui:fileUpload.itemGroup>
    </ui:fileUpload.root>
    <ui:field.helperText>We use this for your application review.</ui:field.helperText>
    <ui:field.errorText />
</ui:field.root>

Show accepted and rejected files

Picked files are listed from an itemTemplate: author the item once and FileUpload clones it for every accepted or rejected file. A rejected item shows why in its itemError part. Drop a file over 1.5 MB, a non-image or a third file to see a rejection.

Portfolio Images

Drop up to two images

Large files will appear in a rejected list below.

Accepted files

No files selected yet.

Rejected files

No rejected files.

<ui:fileUpload.root name="portfolio[]" accept="image/*" maxFileSize="1500000" maxFiles="2">
    <ui:fileUpload.label>Portfolio Images</ui:fileUpload.label>
    <ui:fileUpload.dropzone>
        <div class="grid gap-1">
            <div class="text-sm font-medium">Drop up to two images</div>
            <div class="text-muted-foreground text-sm">Large files will appear in a rejected list below.</div>
        </div>
        <div class="flex items-center gap-2">
            <ui:fileUpload.trigger>Select images</ui:fileUpload.trigger>
            <ui:fileUpload.clearTrigger />
        </div>
    </ui:fileUpload.dropzone>

    <f:comment>
        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.
    </f:comment>
    <primitives:fileUpload.itemTemplate>
        <ui:fileUpload.fileItem>
            <ui:fileUpload.itemPreview match="image/*">
                <ui:fileUpload.itemPreviewImage />
            </ui:fileUpload.itemPreview>
            <ui:fileUpload.itemPreview match=".*">
                <ui:fileUpload.filePreviewFallback />
            </ui:fileUpload.itemPreview>

            <div class="grid min-w-0 flex-1 gap-0.5">
                <ui:fileUpload.fileName />
                <ui:fileUpload.fileMeta />
                <ui:fileUpload.fileError />
            </div>

            <ui:fileUpload.fileDeleteTrigger />
        </ui:fileUpload.fileItem>
    </primitives:fileUpload.itemTemplate>

    <div class="grid gap-4 md:grid-cols-2">
        <div class="grid gap-2">
            <div class="text-sm font-medium">Accepted files</div>
            <ui:fileUpload.itemGroup>
                <ui:fileUpload.emptyState>No files selected yet.</ui:fileUpload.emptyState>
            </ui:fileUpload.itemGroup>
        </div>
        <div class="grid gap-2">
            <div class="text-sm font-medium">Rejected files</div>
            <ui:fileUpload.itemGroup type="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FileUploadItemType::Rejected')}">
                <ui:fileUpload.emptyState type="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FileUploadItemType::Rejected')}">No rejected files.</ui:fileUpload.emptyState>
            </ui:fileUpload.itemGroup>
        </div>
    </div>
</ui:fileUpload.root>

Preview images and other files

Add several itemPreview parts to the item template, each with a match MIME type pattern such as image/*. The first part that matches the file shows, the others hide: an image preview and a generic fallback for everything else.

Attachments

Drag files here or choose from your device

Images and PDFs up to 5 files.

No files selected yet.

<ui:fileUpload.root name="attachments[]" maxFiles="5" accept="image/*,.pdf">
    <ui:fileUpload.label>Attachments</ui:fileUpload.label>
    <ui:fileUpload.dropzone>
        <div class="grid gap-1">
            <div class="text-sm font-medium">Drag files here or choose from your device</div>
            <div class="text-muted-foreground text-sm">Images and PDFs up to 5 files.</div>
        </div>
        <ui:fileUpload.trigger>Choose files</ui:fileUpload.trigger>
    </ui:fileUpload.dropzone>

    <f:comment>
        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.
    </f:comment>
    <primitives:fileUpload.itemTemplate>
        <ui:fileUpload.fileItem>
            <ui:fileUpload.itemPreview match="image/*">
                <ui:fileUpload.itemPreviewImage />
            </ui:fileUpload.itemPreview>
            <ui:fileUpload.itemPreview match=".*">
                <ui:fileUpload.filePreviewFallback />
            </ui:fileUpload.itemPreview>

            <div class="grid min-w-0 flex-1 gap-0.5">
                <ui:fileUpload.fileName />
                <ui:fileUpload.fileMeta />
                <ui:fileUpload.fileError />
            </div>

            <ui:fileUpload.fileDeleteTrigger />
        </ui:fileUpload.fileItem>
    </primitives:fileUpload.itemTemplate>

    <ui:fileUpload.itemGroup>
        <ui:fileUpload.emptyState>No files selected yet.</ui:fileUpload.emptyState>
    </ui:fileUpload.itemGroup>
</ui:fileUpload.root>

Translate the labels

FileUpload translates three labels: dropzone (the aria-label of the dropzone), itemPreview (the alt text of a preview image) and deleteFile (the aria-label of a delete button). The last two take a %fileName% placeholder, which the browser replaces with the name of the file:

<ui:fileUpload.root
    translations="{itemPreview: 'Vorschau von %fileName%', deleteFile: 'Datei %fileName% entfernen'}"
></ui:fileUpload.root>

Write %fileName%, not {fileName}: Fluid reads a curly-brace expression inside a string as a variable and strips it. A client script passes a function of the File instead of a text. Leave out itemPreview or deleteFile to keep the built-in text. To translate per locale, read the texts from your own locallang.xlf with f:translate.

Upload a folder

Set directory to pick a whole folder in browsers that support webkitdirectory.

Asset Folder

Select a directory

Useful for importing grouped assets or media folders.

No files selected yet.

<ui:fileUpload.root name="assets[]" directory="{true}" maxFiles="20">
    <ui:fileUpload.label>Asset Folder</ui:fileUpload.label>
    <ui:fileUpload.dropzone>
        <div class="grid gap-1">
            <div class="text-sm font-medium">Select a directory</div>
            <div class="text-muted-foreground text-sm">Useful for importing grouped assets or media folders.</div>
        </div>
        <ui:fileUpload.trigger>Choose folder</ui:fileUpload.trigger>
    </ui:fileUpload.dropzone>

    <primitives:fileUpload.itemTemplate>
        <ui:fileUpload.fileItem>
            <ui:fileUpload.itemPreview match="image/*">
                <ui:fileUpload.itemPreviewImage />
            </ui:fileUpload.itemPreview>
            <ui:fileUpload.itemPreview match=".*">
                <ui:fileUpload.filePreviewFallback />
            </ui:fileUpload.itemPreview>

            <div class="grid min-w-0 flex-1 gap-0.5">
                <ui:fileUpload.fileName />
                <ui:fileUpload.fileMeta />
                <ui:fileUpload.fileError />
            </div>

            <ui:fileUpload.fileDeleteTrigger />
        </ui:fileUpload.fileItem>
    </primitives:fileUpload.itemTemplate>

    <ui:fileUpload.itemGroup>
        <ui:fileUpload.emptyState>No files selected yet.</ui:fileUpload.emptyState>
    </ui:fileUpload.itemGroup>
</ui:fileUpload.root>

Build your own item layout

The itemTemplate takes any markup. Leave out parts you can do without (this demo has no itemSizeText) and add your own, like a running "3 / 5 files selected" counter. Rejected files can have a template of their own: add a second itemTemplate with type="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FileUploadItemType::Rejected')}", here one without a preview. Without it, rejected items use the accepted template.

Your own elements are ui:refs with context="fileUpload", in the root's slot or in the item template. A subclass of FileUpload fills them in render(), which runs after every change. fileValue() maps the data-value of a rendered item back to its File, which is how the demo shows each photo's modified date.

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.

No photos selected yet.

Rejected

Nothing was rejected.

<ui:fileUpload.root name="photos[]" accept="image/*" maxFiles="5" autoMount="{false}" rootId="custom-layout">
    <div class="flex items-center justify-between gap-4">
        <ui:fileUpload.label>Event Photos</ui:fileUpload.label>
        <div {ui:ref(name: 'filesCounter', context: 'fileUpload')} class="text-muted-foreground text-xs">0 / 5 files selected</div>
    </div>
    <ui:fileUpload.dropzone>
        <div class="grid gap-1">
            <div class="text-sm font-medium">Drop photos here or choose from your device</div>
            <div class="text-muted-foreground text-sm">Up to 5 images. File size is intentionally not shown here.</div>
        </div>
        <ui:fileUpload.trigger>Choose photos</ui:fileUpload.trigger>
    </ui:fileUpload.dropzone>

    <f:comment>
        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.
    </f:comment>
    <f:comment>
        `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.
    </f:comment>
    <primitives:fileUpload.itemTemplate>
        <primitives:fileUpload.item class="flex items-center gap-3 rounded-lg border bg-background p-2 shadow-xs">
            <ui:fileUpload.itemPreview match="image/*" class="size-14">
                <ui:fileUpload.itemPreviewImage />
            </ui:fileUpload.itemPreview>
            <ui:fileUpload.itemPreview match=".*" class="size-14">
                <ui:fileUpload.filePreviewFallback />
            </ui:fileUpload.itemPreview>

            <div class="grid min-w-0 flex-1 gap-0.5">
                <ui:fileUpload.fileName class="truncate text-sm font-semibold" />
                <div {ui:ref(name: 'itemModifiedDate', context: 'fileUpload')} class="text-muted-foreground text-[11px]"></div>
            </div>

            <primitives:fileUpload.itemDeleteTrigger class="button button-ghost text-muted-foreground h-8 px-2.5 text-xs">Remove</primitives:fileUpload.itemDeleteTrigger>
        </primitives:fileUpload.item>
    </primitives:fileUpload.itemTemplate>

    <f:comment>
        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.
    </f:comment>
    <primitives:fileUpload.itemTemplate type="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FileUploadItemType::Rejected')}">
        <primitives:fileUpload.item class="border-destructive/30 bg-destructive/5 grid gap-0.5 rounded-lg border px-3 py-2">
            <div class="flex items-center justify-between gap-3">
                <ui:fileUpload.fileName class="truncate text-sm font-medium" />
                <primitives:fileUpload.itemDeleteTrigger class="button button-ghost text-muted-foreground h-7 px-2 text-xs">Dismiss</primitives:fileUpload.itemDeleteTrigger>
            </div>
            <ui:fileUpload.fileError />
        </primitives:fileUpload.item>
    </primitives:fileUpload.itemTemplate>

    <ui:fileUpload.itemGroup>
        <ui:fileUpload.emptyState>No photos selected yet.</ui:fileUpload.emptyState>
    </ui:fileUpload.itemGroup>

    <div class="grid gap-2">
        <div class="text-sm font-medium">Rejected</div>
        <ui:fileUpload.itemGroup type="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FileUploadItemType::Rejected')}">
            <ui:fileUpload.emptyState type="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FileUploadItemType::Rejected')}">Nothing was rejected.</ui:fileUpload.emptyState>
        </ui:fileUpload.itemGroup>
    </div>
</ui:fileUpload.root>

<vite:asset entry="EXT:docs/Resources/Private/Components/ui/FileUploadExamples/CustomLayout.entry.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.hydrator.query<HTMLElement>('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.
     * query(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.hydrator.queryAll<HTMLElement>('item').forEach(itemEl => {
            const dateEl = this.hydrator.query<HTMLElement>('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('ui:fileUpload', 'custom-layout', ({ props }) => {
    const fileUpload = new FileUploadWithCounter(props);
    fileUpload.init();
    return fileUpload;
});

Ask before deleting a file

itemDeleteTrigger deletes right away. To ask first, pair the file upload with a Dialog: render both with autoMount="{false}" and a fixed rootId, and listen for the click on the item group in the capture phase. Call event.stopImmediatePropagation() there to keep the built-in delete from running, find the file with fileValue() and call api.deleteFile() once the dialog is confirmed.

Items are cloned again on every change, so the listener belongs on the item group.

Documents

Drop documents here or choose from your device

Removing a file asks for confirmation first.

No documents selected yet.

<ui:fileUpload.root name="documents[]" accept=".pdf,.doc,.docx" maxFiles="5" autoMount="{false}" rootId="delete-confirm">
    <ui:fileUpload.label>Documents</ui:fileUpload.label>
    <ui:fileUpload.dropzone>
        <div class="grid gap-1">
            <div class="text-sm font-medium">Drop documents here or choose from your device</div>
            <div class="text-muted-foreground text-sm">Removing a file asks for confirmation first.</div>
        </div>
        <ui:fileUpload.trigger>Choose files</ui:fileUpload.trigger>
    </ui:fileUpload.dropzone>

    <primitives:fileUpload.itemTemplate>
        <ui:fileUpload.fileItem>
            <ui:fileUpload.itemPreview match=".*">
                <ui:fileUpload.filePreviewFallback />
            </ui:fileUpload.itemPreview>

            <div class="grid min-w-0 flex-1 gap-0.5">
                <ui:fileUpload.fileName />
                <ui:fileUpload.fileMeta />
            </div>

            <ui:fileUpload.fileDeleteTrigger />
        </ui:fileUpload.fileItem>
    </primitives:fileUpload.itemTemplate>

    <ui:fileUpload.itemGroup>
        <ui:fileUpload.emptyState>No documents selected yet.</ui:fileUpload.emptyState>
    </ui:fileUpload.itemGroup>
</ui:fileUpload.root>

<f:comment>
    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.
</f:comment>
<ui:dialog.root autoMount="{false}" rootId="delete-confirm" role="{f:constant(name: 'Jramke\FluidPrimitives\Enum\DialogRole::AlertDialog')}">
    <ui:dialog.content>
        <ui:dialog.header>
            <ui:dialog.title>Remove file?</ui:dialog.title>
            <ui:dialog.description>
                <span {ui:ref(name: 'pendingFileName', context: 'dialog')}>This file</span> will be removed from the upload. This can't be undone.
            </ui:dialog.description>
        </ui:dialog.header>
        <ui:dialog.footer>
            <ui:dialog.close asChild="{true}">
                <ui:button variant="secondary">Cancel</ui:button>
            </ui:dialog.close>
            <button type="button" {ui:ref(name: 'confirmTrigger', context: 'dialog')} class="button button-default h-8 px-3.5 py-2.5">Remove file</button>
        </ui:dialog.footer>
    </ui:dialog.content>
</ui:dialog.root>

<vite:asset entry="EXT:docs/Resources/Private/Components/ui/FileUploadExamples/DeleteConfirmation.entry.ts" />

Save files with Extbase

FileUpload renders a native <input type="file">, so Extbase's #[FileUpload] property attribute works as it does with f:form.upload, without special controller code.

class Conference extends AbstractEntity
{
    #[FileUpload(
        validation: [
            'required' => 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<FileReference>
     */
    #[FileUpload(
        validation: [
            'fileSize' => ['minimum' => '10K', 'maximum' => '10M'],
            'mimeType' => ['allowedMimeTypes' => ['image/jpeg', 'image/png']],
            'fileExtension' => ['allowedFileExtensions' => ['jpg', 'jpeg', 'png']],
        ],
        uploadFolder: '1:/user_upload/conference_photos/',
    )]
    protected ObjectStorage $photos;
}

Use ui:form.root and set maxFiles on FileUpload to match the property: 1 for a single FileReference, more for an ObjectStorage<FileReference>. For a multi-file property, add the [] suffix to name yourself, as for a CheckboxGroup bound to an array property:

<ui:form.root action="update" objectName="conference" object="{conference}">
    <ui:field.root name="logo">
        <ui:fileUpload.root name="logo" accept="image/jpeg,image/png" maxFiles="1">
            <ui:fileUpload.label>Logo</ui:fileUpload.label>
            <ui:fileUpload.dropzone>
                <ui:fileUpload.trigger>Choose logo</ui:fileUpload.trigger>
            </ui:fileUpload.dropzone>
            <ui:fileUpload.itemGroup>
                <ui:fileUpload.emptyState>No logo selected yet.</ui:fileUpload.emptyState>
            </ui:fileUpload.itemGroup>
        </ui:fileUpload.root>
    </ui:field.root>

    <ui:field.root name="photos">
        <ui:fileUpload.root name="photos[]" accept="image/jpeg,image/png" maxFiles="10">
            <ui:fileUpload.label>Photos</ui:fileUpload.label>
            <ui:fileUpload.dropzone>
                <ui:fileUpload.trigger>Choose photos</ui:fileUpload.trigger>
            </ui:fileUpload.dropzone>
            <ui:fileUpload.itemGroup>
                <ui:fileUpload.emptyState>No photos selected yet.</ui:fileUpload.emptyState>
            </ui:fileUpload.itemGroup>
        </ui:fileUpload.root>
    </ui:field.root>
</ui:form.root>

The form posts with extbase.post(), which sends multipart/form-data, so the <form> needs no enctype.

accept only filters the file picker in the browser, #[FileUpload] validates the upload itself. List the same MIME types and extensions in accept, in #[FileUpload] and in the allowed key of the TCA type=file column.

Edit files that are already uploaded

In an edit form, render the stored files as items with type="existing" inside the same itemGroup as the newly picked files. Pair each delete trigger with ui:fileUploadDeleteCheckbox, which renders the signed @delete token Extbase uses to remove the file reference on submit. Give each existing item a value, such as the uid of its file reference, so their ids stay unique.

Keep the itemTemplate next to the existing items: newly picked files are cloned from it, and picking one throws without it.

<ui:form.root action="update" objectName="conference" object="{conference}">
    <ui:field.root name="photos[]">
        <ui:fileUpload.root
            accept="image/jpeg,image/png"
            maxFiles="10"
            existingFilesCount="{conference.photos -> f:count()}"
        >
            <ui:fileUpload.label>Photos</ui:fileUpload.label>
            <ui:fileUpload.dropzone>
                <ui:fileUpload.trigger>Choose photos</ui:fileUpload.trigger>
            </ui:fileUpload.dropzone>

            <primitives:fileUpload.itemTemplate>
                <!-- the item markup for newly picked files -->
            </primitives:fileUpload.itemTemplate>

            <ui:fileUpload.itemGroup>
                <f:for each="{conference.photos}" as="fileReference">
                    <ui:fileUpload.fileItem type="existing" value="{fileReference.uid}">
                        <f:image image="{fileReference}" width="40" height="40" />
                        <ui:fileUpload.fileName
                            >{fileReference.originalResource.name}</ui:fileUpload.fileName
                        >
                        <ui:fileUploadDeleteCheckbox
                            fileReference="{fileReference}"
                            class="hidden"
                        />
                        <ui:fileUpload.fileDeleteTrigger />
                    </ui:fileUpload.fileItem>
                </f:for>
                <ui:fileUpload.emptyState>No photos selected yet.</ui:fileUpload.emptyState>
            </ui:fileUpload.itemGroup>
        </ui:fileUpload.root>
    </ui:field.root>
</ui:form.root>

A click on the delete trigger checks the checkbox next to it and hides the item right away, like removing a newly picked file. The FileReference is deleted when the form is submitted. Put the checkbox next to fileDeleteTrigger, a <button> cannot contain an <input>, and hide it with class="hidden".

ui:fileUploadDeleteCheckbox needs an objectName on the enclosing ui:form.root that matches the argument name of the controller action. It reads property from the surrounding ui:field.root unless you pass it.

existingFilesCount counts the slots the existing items use, so maxFiles and the TOO_MANY_FILES rejection include them.

API Reference

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

fileUpload.root

Contains every part of the file upload. Renders a <div> element.

Name	Description	Required	Default
`name`	`string` The name of the underlying file input. Inherited from a surrounding field when available.	No	-
`disabled`	`boolean` Whether the file upload is disabled. Inherited from a surrounding field when available.	No	-
`invalid`	`boolean` Whether the file upload is invalid. Inherited from a surrounding field when available.	No	-
`required`	`boolean` Whether the file upload is required. Inherited from a surrounding field when available.	No	-
`readOnly`	`boolean` Whether the file upload is read-only. Inherited from a surrounding field when available.	No	-
`accept`	`mixed` The accepted file types, e.g. `image/*` or `{ 'image/png': ['.png'] }`.	No	-
`allowDrop`	`boolean` Whether to allow drag and drop in the dropzone element.	No	true
`maxFiles`	`integer` The maximum number of files that can be selected.	No	1
`existingFilesCount`	`integer` The number of already-persisted files shown outside the machine's own file list (e.g. as `type="existing"` items), so it can be subtracted from `maxFiles` and the remaining-slots count also accounts for them. Deliberately a plain count, not a list of `File` objects: whatever ends up in the machine's own accepted files also ends up in the hidden input's `FileList` and gets resubmitted on the next form post, which would silently overwrite an already-stored file with placeholder content reconstructed from just its name/size.	No	0
`maxFileSize`	`integer` The maximum file size in bytes.	No	-
`minFileSize`	`integer` The minimum file size in bytes.	No	-
`preventDocumentDrop`	`boolean` Whether to prevent a file drop outside of the dropzone from navigating the document.	No	true
`capture`	`Enum\FileUploadCapture` The camera to use to capture media on mobile devices.	No	-
`directory`	`boolean` Whether to accept whole directories instead of files. Only works in webkit based browsers.	No	false
`translations`	`array` Localized file upload labels. `itemPreview` and `deleteFile` take a `%fileName%` placeholder, and are functions of the `File` in a client script. Use `f:translate` for per-template localization overrides when needed.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`rootId`	`string` The root ID of the component, used for hydration and identification.	No	-
`ids`	`array` The IDs of of the component parts for composition.	No	[]
`autoMount`	`boolean` Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()`	No	true
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-file-upload-root`	<uid>
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only
`data-dragging`	Present when in the dragging state

fileUpload.label

The label for the file input. Renders a <label> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-file-upload-label`	<uid>
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-required`	Present when required

fileUpload.dropzone

The drag-and-drop target and click-to-open surface. Renders a <div> element with role="button".

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-file-upload-dropzone`	<uid>
`data-invalid`	Present when invalid
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only
`data-dragging`	Present when in the dragging state

fileUpload.hiddenInput

The native file input used for form submission. Renders a visually hidden <input type="file"> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

fileUpload.trigger

Opens the file picker dialog. Renders a <button> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-file-upload-trigger`	<uid>
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only
`data-invalid`	Present when invalid

fileUpload.itemGroup

Groups accepted or rejected file items, selected via the type prop (Jramke\FluidPrimitives\Enum\FileUploadItemType). Renders a <div> element.

Name	Description	Required	Default
`type`	`Enum\FileUploadItemType` Which file list this group renders, `accepted` or `rejected`.	No	Accepted
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-file-upload-item-group`	<uid>
`data-disabled`	Present when disabled
`data-type`	The type of the item

fileUpload.emptyState

Shown while an itemGroup has no items yet. Renders a <div> element.

Name	Description	Required	Default
`type`	`Enum\FileUploadItemType` Which file list this empty state belongs to - must match the enclosing item group's own `type`, to keep ids unique when both groups render in the same root.	No	Accepted
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

fileUpload.itemTemplate

Wraps the item markup for accepted files, or rejected files when type is set to Jramke\FluidPrimitives\Enum\FileUploadItemType::Rejected (falls back to the accepted template when no dedicated rejected one is given). Renders a <template> element - never visible itself, cloned per file.

Name	Description	Required	Default
`type`	`Enum\FileUploadItemType` Which files this template is for. `accepted` (the default) also doubles as the fallback rejected items use when no dedicated `rejected` template is given - see FileUpload.ts's resolveItemTemplatePart().	No	Accepted

fileUpload.item

One file. Accepted/rejected items are only ever rendered from an itemTemplate; an already-persisted file can be authored directly with type="existing". Renders a <div> element.

Name	Description	Required	Default
`type`	`string` The item's kind, e.g. `accepted`, `rejected`, or a custom value such as `existing` for an already-persisted file authored directly rather than populated from a `ui:template` stencil.	No	'accepted'
`value`	`string` A unique identifier for this item, e.g. a persisted file reference's own `uid`. Not needed for `accepted`/`rejected` items populated from `itemTemplate` - the client re-stamps those with the picked file's own value on mount. Required when authoring more than one `type=" existing"` item directly, so the client can tell their `item`/`itemName`/`itemSizeText`/`itemDeleteTrigger`/`itemError` parts apart.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-file-upload-item`	<uid>
`data-disabled`	Present when disabled
`data-type`	The type of the item

fileUpload.itemName

Displays the file's name. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-file-upload-item-name`	<uid>
`data-disabled`	Present when disabled
`data-type`	The type of the item

fileUpload.itemSizeText

Displays the file's formatted size. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-file-upload-item-size-text`	<uid>
`data-disabled`	Present when disabled
`data-type`	The type of the item

fileUpload.itemError

Displays a rejected file's validation errors, hidden by default. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

fileUpload.itemPreview

A preview variant for an item, shown when its match MIME type pattern matches the file. Renders a <div> element.

Name	Description	Required	Default
`match`	`string` A file MIME type pattern (e.g. `image/`) this preview variant should be used for. The first `itemPreview` whose `match` matches the file wins; use `.` as a catch-all fallback.	No	'.*'
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-file-upload-item-preview`	<uid>
`data-disabled`	Present when disabled
`data-type`	The type of the item

fileUpload.itemPreviewImage

Displays an image preview, only rendered for image files. Renders an <img> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-file-upload-item-preview-image`	<uid>
`data-disabled`	Present when disabled
`data-type`	The type of the item

fileUpload.itemPreviewFallback

Displays a generic fallback (e.g. the file extension) inside a non-image itemPreview variant. Renders a <div> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

fileUpload.itemDeleteTrigger

Removes a single accepted or rejected file. Renders a <button> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-file-upload-item-delete-trigger`	<uid>
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only
`data-type`	The type of the item

fileUpload.clearTrigger

Clears every accepted file. Renders a <button> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-file-upload-clear-trigger`	<uid>
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only

Machine JavaScript API

Name	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
`readOnly`	`boolean`	Whether the file input is in read-only mode
`transforming`	`boolean`	Whether files are currently being transformed via `transformFiles`
`maxFilesReached`	`boolean`	Whether the maximum number of files has been reached
`remainingFiles`	`number`	The number of files that can still be added
`openFilePicker`	`VoidFunction`	Function to open the file dialog
`deleteFile`	`(file: File, type?: ItemType \| undefined) => 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 \| null) => boolean`	Sets the clipboard files Returns `true` if the clipboard data contains files, `false` otherwise.
`getRootState`	`() => RootState`	Returns the state of the root
`getDropzoneState`	`() => DropzoneState`	Returns the state of the dropzone
`getTriggerState`	`() => TriggerState`	Returns the state of the trigger
`getItemGroupState`	`(props: ItemGroupProps) => ItemGroupState`	Returns the state of the item group
`getItemState`	`(props: ItemProps) => ItemState`	Returns the state of the item