Pintura Image Editor v8.53.6

Setting up Pintura Image Editor with jQuery

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

We only have to include the jquery-pintura/pintura.js file and the jquery-pintura/pintura.css file in our project and we're good to go.

Default 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="jquery-pintura/pintura.css" />

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

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

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

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

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

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('./my-image.jpeg').then((res) => {
    console.log('Image loaded', res);
});

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

// Run loadImage method
$('.my-editor')
    .pintura('loadImage', './my-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.

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: './my-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: './my-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 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="jquery-pintura/pintura.css" />

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

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

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

<script>
    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: './my-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

Setting up Pintura Image Editor with jQuery

Default implementation example

Events and methods

Modal and overlay editor

Advanced implementation example

Next steps