v8.77.0

Setting up Pintura Image Editor with jQuery

For a quick start use the jQuery example project as a guideline. It includes a normal, modal, and overlay editor example.

Default jQuery implementation example

In the default example below we'll use the pinturaDefault function to quickly add an image editor to another HTML element.

This creates a "default" editor that has all available plugins loaded and comes preset with all plugin default options and English locale. Each of these settings can be adjusted freely.

<!DOCTYPE html>

<link rel="stylesheet" href="pintura/pintura.css" />

<style>
    .my-editor {
        height: 600px;
    }
</style>

<div class="my-editor"></div>

<script src="pintura/pintura-iife.js"></script>
<script src="jquery-pintura/useEditorWithJQuery-iife.js"></script>
<script src="jquery.js"></script>

<script>
    // load Pintura with jQuery
    useEditorWithJQuery(jQuery, pintura);

    $('.my-editor').pinturaDefault({
        // The source image to load
        src: 'image.jpeg',

        // This will set a square crop aspect ratio
        imageCropAspectRatio: 1,
    });
</script>

jQuery Events and methods

When using the jQuery methods $(selector).pintura() or $(selector).pinturaDefault() the returned object is a jQuery result not an instance of the editor.

To handle events fired by the editor we have to prepend each event we want to listen to with pintura:

$('.my-editor').on('pintura:load', (e) => {
    // Handle event
    console.log('Image loaded', e.detail);
});

To run editor methods we have to do it the jQuery way, this means we use the pintura scope and then we pass the method name as a string and next the parameters.

// Creating an editor without jQuery
const editor = createDefaultEditor();

// Run loadImage method
editor.loadImage('image.jpeg').then((res) => {
    console.log('Image loaded', res);
});

// Creating an editor with jQuery
$('.my-editor').pinturaDefault();

// Run loadImage method
$('.my-editor')
    .pintura('loadImage', 'image.jpeg')
    .then((res) => {
        console.log('Image loaded', res);
    });

When we create a modal or overlay editor the factory method returns a normal editor instance. We can interact with this instance without having to convert method names to a string or prepend events with pintura:, see below.

jQuery Modal and overlay editor

The jQuery API also allows creation of modal and overlay editors. Instead of the $(selector).pintura syntax we can use the methods exported by the editor API as these are available on the $.fn.pintura property. See the exports section for an overview of the available methods and properties.

This will open the editor in a modal. Note that this is not a default editor, to open a default editor use openDefaultEditor instead of openEditor.

const editor = $.fn.pintura.openDefaultEditor({
    src: 'image.jpeg',

    // This will set a square crop aspect ratio
    imageCropAspectRatio: 1,
});

// Remove the image
editor.removeImage();

Listening for events on the editor modal can be done like shown below.

const editor = $.fn.pintura.openDefaultEditor({
    src: 'image.jpeg',

    // This will set a square crop aspect ratio
    imageCropAspectRatio: 1,
});

editor.on('load', (e) => {
    // Handle event
    console.log('Image loaded', e.detail);
});

Advanced jQuery implementation example

If we want to create a custom editor, using a custom set of plugins, locale, and available options, then we can opt to use the $.fn.pintura method.

We now have to set the available plugins, load the correct locale objects, and set the default plugin options. While a lot more verbose this does allow us to create a more optimal editor package as we're omitting unneeded logic.

<!DOCTYPE html>

<link rel="stylesheet" href="pintura/pintura.css" />

<style>
    .my-editor {
        height: 600px;
    }
</style>

<div class="my-editor"></div>

<script src="pintura/pintura-iife.js"></script>
<script src="jquery-pintura/useEditorWithJQuery-iife.js"></script>
<script src="jquery.js"></script>

<script>
    // load Pintura with jQuery
    useEditorWithJQuery(jQuery, pintura);

    const {
        // Get the default image reader and writer
        createDefaultImageReader,
        createDefaultImageWriter,

        // The method used to register the plugins
        setPlugins,

        // The plugins we want to use
        plugin_crop,
        plugin_finetune,
        plugin_annotate,

        // The user interface and plugin locale objects
        locale_en_gb,
        plugin_crop_locale_en_gb,
        plugin_finetune_locale_en_gb,
        plugin_annotate_locale_en_gb,

        // Because we use the annotate plugin we also need
        // to import the markup editor locale and the shape preprocessor
        markup_editor_locale_en_gb,
        createDefaultShapePreprocessor,

        // Import the default configuration for the markup editor and finetune plugins
        markup_editor_defaults,
        plugin_finetune_defaults,
    } = $.fn.pintura;

    // This registers the plugins with Pintura Image Editor
    setPlugins(plugin_crop, plugin_finetune, plugin_annotate);

    // Append the editor
    $('.my-editor').pintura({
        // The source image to load
        src: 'image.jpeg',

        // This will read the image data (required)
        imageReader: createDefaultImageReader(),

        // This will write the output image
        imageWriter: createDefaultImageWriter(),

        // The markup editor default options, tools, shape style controls
        ...markup_editor_defaults,

        // The finetune util controls
        ...plugin_finetune_defaults,

        // This handles complex shapes like arrows / frames
        shapePreprocessor: createDefaultShapePreprocessor(),

        // This will set a square crop aspect ratio
        imageCropAspectRatio: 1,

        // The icons and labels to use in the user interface (required)
        locale: {
            ...locale_en_gb,
            ...plugin_crop_locale_en_gb,
            ...plugin_finetune_locale_en_gb,
            ...plugin_annotate_locale_en_gb,
            ...markup_editor_locale_en_gb,
        },
    });
</script>

Next steps

With the editor set up, we can continue to configure the editor to our liking by adjusting the available options exposed by the editor API