Allow to crop local and remote image before uploading them through a classic form.

Installs: 42 720

Dependents: 1

Suggesters: 1

Security: 0

Stars: 14

Watchers: 7

Forks: 14

Open Issues: 0



v2.0.1 2020-05-01 14:02 UTC


Build Status Scrutinizer Code Quality Latest Stable Version Total Downloads


PrestaImageBundle is a Symfony bundle providing tools to resize local/remote images before uploading them through a classic form. It uses Cropper jQuery plugin.


Require the bundle as a Composer dependency

composer require presta/image-bundle

Configure the bundle

You must use the bootstrap_4.html.twig form theme into config/packages/twig.yaml.

        - "@PrestaImage/form/bootstrap_4.html.twig"

Note: you can also use the bootstrap_3.html.twig form theme instead.

You must include the routing into config/routes.yaml:

    resource: "@PrestaImageBundle/Resources/config/routing.yaml"

See VichUploader documentation to configure the bundle.

Install assets

See Cropper documentation to install assets.

Don't forget to include the following assets in your page:

  • /path/to/cropper/dist/cropper.min.css
  • /path/to/cropper/dist/cropper.min.js
  • /path/to/cropper/dist/jquery-cropper.min.js
  • @PrestaImageBundle/Resources/public/css/cropper.css
  • @PrestaImageBundle/Resources/public/js/cropper.js

Note that jQuery and Bootstrap are required and must be included.

How to: implementation examples


Initialize cropper

(function(w, $) {

    'use strict';

    $(function() {
        $('.cropper').each(function() {
            new Cropper($(this));

})(window, jQuery);

Use the form type


use Presta\ImageBundle\Form\Type\ImageType;

public function buildForm(FormBuilderInterface $builder, array $options): void
        ->add('image', ImageType::class)

Available options for the ImageType:

  • aspect_ratios (array): a list of aspect ratio to apply when resizing an image
  • cropper_options (array): a list of options supported by cropper (default: ['autoCropArea' => 1])
  • max_width (int): the max width of the cropped image send to server (default: 320)
  • max_height (int): the max height of the cropped image send to server (default: 180)
  • preview_width (string): the max width to use when displaying the image preview - can be in px, % or other css value (default: '320px')
  • preview_height (string): the max height to use when displaying the image preview - can be in px, % or other css value (default: '180px')
  • upload_button_class (string): class of the button (default: 'btn btn-sm btn-primary')
  • upload_button_icon (string): class of the button (default: 'fa fa-upload')
  • cancel_button_class (string): class of the button (default: 'btn btn-default')
  • save_button_class (string): class of the button (default: 'btn btn-primary')
  • download_uri (string): the path where the image is located (default: null, automatically set)
  • download_link (bool): whether the end user should be able to add a remote image by URL (default: true)
  • enable_locale (bool): whether to enable the locale upload (default: true)
  • enable_remote (bool): whether to enable the remote upload (default: true)
  • upload_mimetype (string): format of the image to be uploaded (default: image/png)
    (Note: If the chosen mimetype is not supported by the browser, it will silently fall back to image/png)
  • upload_quality (float): quality (0..1) of uploaded image for lossy imageformats (eg. image/jpeg) (default: 0.92)


You can find Cropper options here.

The max_width and max_height options are used to define maximum size the cropped uploaded image will be. Bigger images (after cropping) are scaled down.

Security Note: NEVER rely on this size constraints and the format settings as they can be easily manipulated client side. ALWAYS validate the image-data, -size, -format at server side!


Pull requests are welcome.

Thanks to everyone who has contributed already.

This project is supported by PrestaConcept

Lead Developer : @J-Ben87

Released under the MIT License