Symfony UX Dropzone

Uploading multiple files

Upload several files at once, pass the standard multiple option (inherited from FileType):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// ...
use Symfony\UX\Dropzone\Form\DropzoneType;

class CommentFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            // ...
            ->add('photos', DropzoneType::class, [
                'multiple' => true,
            ])
            // ...
        ;
    }

    // ...
}

In multiple mode, the Dropzone accumulates files across successive selections instead of replacing the previous one, displays a preview for each selected file and lets the user remove files individually before submitting.

In this mode, the dropzone:connect, dropzone:change and dropzone:remove events are dispatched (dropzone:clear is not dispatched, as there is no clear button in multiple mode). Beware that dropzone:change carries a single File in single-file mode, but a FileList in multiple mode. The dropzone:remove event is dispatched when a file is removed, and carries the removed File in event.detail.

The label of the per-file remove button can be changed with the remove_label option (default 'Remove'). It goes through the form's translation domain, and the accessible name of each button is that label followed by the file name:

1
2
3
4

->add('photos', DropzoneType::class, [
    'multiple' => true,
    'remove_label' => 'Delete',
])

Customizing the design

Symfony UX Dropzone provides a default stylesheet in order to ease usage. You can disable it to add your own design if you wish.

In assets/controllers.json, disable the default stylesheet by switching the @symfony/ux-dropzone/dist/style.min.css autoimport to false:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
    "controllers": {
        "@symfony/ux-dropzone": {
            "dropzone": {
                "enabled": true,
                "fetch": "eager",
                "autoimport": {
                    "@symfony/ux-dropzone/dist/style.min.css": false
                }
            }
        }
    },
    "entrypoints": []
}

Once done, the default stylesheet won't be used anymore and you can implement your own CSS on top of the Dropzone.

Extend the default behavior

Symfony UX Dropzone allows you to extend its default behavior using a custom Stimulus controller:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// mydropzone_controller.js

import { Controller } from '@hotwired/stimulus';

export default class extends Controller {
    connect() {
        this.element.addEventListener('dropzone:connect', this._onConnect);
        this.element.addEventListener('dropzone:change', this._onChange);
        this.element.addEventListener('dropzone:clear', this._onClear);
    }

    disconnect() {
        // You should always remove listeners when the controller is disconnected to avoid side-effects
        this.element.removeEventListener('dropzone:connect', this._onConnect);
        this.element.removeEventListener('dropzone:change', this._onChange);
        this.element.removeEventListener('dropzone:clear', this._onClear);
    }

    _onConnect(event) {
        // The dropzone was just created
    }

    _onChange(event) {
        // The dropzone just changed
    }

    _onClear(event) {
        // The dropzone has just been cleared
    }
}

Then in your form, add your controller as an HTML attribute:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// ...
use Symfony\UX\Dropzone\Form\DropzoneType;

class CommentFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            // ...
            ->add('photo', DropzoneType::class, [
                'attr' => ['data-controller' => 'mydropzone'],
            ])
            // ...
        ;
    }

    // ...
}