Symfony
sponsored by SensioLabs
Menu
  • About
  • Documentation
  • Screencasts
  • Cloud
  • Certification
  • Community
  • Businesses
  • News
  • Download
  1. Home
  2. Documentation
  3. Bundles
  4. Symfony UX Dropzone
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud
Search by Algolia

Table of Contents

  • Installation
  • Usage
    • Customizing the design
    • Extend the default behavior
  • Backward Compatibility promise

Symfony UX Dropzone

Edit this page

Symfony UX Dropzone

Symfony UX Dropzone is a Symfony bundle providing light dropzones for file inputs in Symfony Forms. It is part of the Symfony UX initiative.

It allows visitors to drag and drop files into a container instead of having to browse their computer for a file.

Installation

Before you start, make sure you have Symfony UX configured in your app.

Then, install this bundle using Composer and Symfony Flex:

1
2
3
4
5
6
7
8
9
$ composer require symfony/ux-dropzone

# Don't forget to install the JavaScript dependencies as well and compile
$ npm install --force
$ npm run watch

# or use yarn
$ yarn install --force
$ yarn watch

Also make sure you have at least version 3.0 of @symfony/stimulus-bridge in your package.json file.

Usage

The most common usage of Symfony UX Dropzone is to use it as a drop-in replacement of the native FileType class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// ...
use Symfony\UX\Dropzone\Form\DropzoneType;

class CommentFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            // ...
            ->add('photo', DropzoneType::class)
            // ...
        ;
    }

    // ...
}

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/src/style.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/src/style.css": false
                }
            }
        }
    },
    "entrypoints": []
}

Note

Note: you should put the value to false and not remove the line so that Symfony Flex won’t try to add the line again in the future.

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)
    {
        $builder
            // ...
            ->add('photo', DropzoneType::class, [
                'attr' => ['data-controller' => 'mydropzone'],
            ])
            // ...
        ;
    }

    // ...
}

Backward Compatibility promise

This bundle aims at following the same Backward Compatibility promise as the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
We stand with Ukraine.
Version:

Symfony UX is backed by

Online exam, become Sylius certified today

Online exam, become Sylius certified today

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

Avatar of Sam Jarrett, a Symfony contributor

Thanks Sam Jarrett for being a Symfony contributor

1 commit • 1 lines changed

View all contributors that help us make Symfony

Become a Symfony contributor

Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

Learn how to contribute

Symfony™ is a trademark of Symfony SAS. All rights reserved.

  • What is Symfony?
    • Symfony at a Glance
    • Symfony Components
    • Case Studies
    • Symfony Releases
    • Security Policy
    • Logo & Screenshots
    • Trademark & Licenses
    • symfony1 Legacy
  • Learn Symfony
    • Symfony Docs
    • Symfony Book
    • Reference
    • Bundles
    • Best Practices
    • Training
    • eLearning Platform
    • Certification
  • Screencasts
    • Learn Symfony
    • Learn PHP
    • Learn JavaScript
    • Learn Drupal
    • Learn RESTful APIs
  • Community
    • SymfonyConnect
    • Support
    • How to be Involved
    • Code of Conduct
    • Events & Meetups
    • Projects using Symfony
    • Downloads Stats
    • Contributors
    • Backers
  • Blog
    • Events & Meetups
    • A week of symfony
    • Case studies
    • Cloud
    • Community
    • Conferences
    • Diversity
    • Documentation
    • Living on the edge
    • Releases
    • Security Advisories
    • SymfonyInsight
    • Twig
    • SensioLabs
  • Services
    • SensioLabs services
    • Train developers
    • Manage your project quality
    • Improve your project performance
    • Host Symfony projects
    Deployed on
Follow Symfony
Search by Algolia