Editor events

Pintura Image Editor exposes a list of events so we can interact and respond to the editor state appropriatly.

Events overview

These are the events fired by the editor instance.

Name Description
'loadstart' Fired when image loading starts.
'loadabort' Fired when image loading is aborted.
'loaderror' Fired when an error is thrown during image load.
'loadprogress' Fired when loading of the image progresses.
'load' Fired when an image has successfully loaded.
'update' Fired when the imageState is updated.
'processstart' Fired when processing of an image starts.
'processabort' Fired when processing of an image is aborted.
'processerror' Fired when an error is thrown during image processing.
'processprogress' Fired when processing of the image progresses.
'process' Fired when an image has been processed.
'undo' Fired on undo action.
'redo' Fired on redo action.
'revert' Fired on revert action. Will only be fired if willRevert resolves with true.
'destroy' Fired when the editor is destroyed.
'close' Fired when the editor is closed with the close button.

Instances created with the openEditor JavaScript API fire a couple additional events.

Name Description
'show' Fired when the modal is shown.
'hide' Fired when the modal is hidden.

When using the Markup Editor the following additional events are fired.

Name Description
'addshape' Fired when a shape is added, receives added shape.
'selectshape' Fired when a shape is selected, receives selected shape.
'udpateshape' Fired when a shape is updated, receives updated shape.
'removeshape' Fired when a shape is removed, receives removed shape.

Subscribing to events

When using the native version of Pintura Image Editor events can be subscribed to using the on method exposed on the Pintura Image Editor instance. An alternative method to subscribe to events is to use the handleEvent property.

If we're using the Custom Elements API we can listen for events using an EventListener.

Events always only return one value which is either passed as a parameter or set as the detail property of the CustomEvent.

// pintura instance
editor.on('load', (res) => {
    console.log(res);
    // logs: { src:…, dest:… , size:… }
});

Using the handleEvent property.

// pintura instance
editor.handleEvent = (type, detail) => {
    if (type === 'process') {
        // handle process event
    }
};

The handleEvent example below will log all fired events to console.

// pintura instance
editor.handleEvent = console.log;

// logs: 'loadstart', undefined
// logs: 'loadprogress', { index: 0, task: 'any-to-file', … }
// logs: 'load', { src:…, dest:… , size:… }
// logs: …

Use addEventListener with Custom Elements. Make sure to prefix events with pintura:.

<pintura-editor src="my-image.jpeg"></pintura-editor>
<script>
    const editor = document.querySelector('pintura-editor');
    editor.addEventListener('pintura:load', (e) => {
        console.log(e.detail);
        // logs: { src:…, dest:… , size:… }
    });
</script>

Events and JavaScript frameworks

When using one of the included JavaScript framework components listening for events works exactly like you would expect for how components work in your framework of choice.

Please see your preferred framework configuration section for more details.

Editor events

loadstart

Fired when an image starts loading.

loadabort

Fired when the image load is aborted. For example when a new image is set while another image is still loading.

loaderror

Fired when the image load process throws an error.

loadprogress

Fired when the image load process makes progress. Receives the task progress event. The task progress event has the following properties.

Name Description
index The index of the task in the processing array.
task The name of the task in the processing array.
taskProgress The current progress of the task between 0 and 1.
taskLengthComputable Is the length of this task computable, is true when the task length will be updated, the editor will show a progress indicator. If is false the editor will show a spinner.
timeStamp The time stamp of the event.

Each task will fire at least a progress event with taskProgress set to 0 and a progress event with taskProgress set to 1. The 0 progress event will always have taskLengthComputable set to false as the editor doesn't know if the length will be computable before the task runs. The taskLengthComputable of the final progress event will either be false or true depending on if progress events were fired.

import { openEditor } from './pintura.js';

const editor = openEditor({
    src: './my-image.jpeg',
});

editor.on('loadprogress', console.log);
// logs: { index: 0, task: 'any-to-file' , taskProgress: 0, taskLengthComputable: false, timeStamp: 1614589213257 }

load

Fired when the src image has finished loading, receives the imageReader output object.

import { openEditor } from './pintura.js';

const editor = openEditor({
    src: './my-image.jpeg',
});

editor.on('load', console.log);
// logs: { src:…, dest:… , size:… }

update

Fired when the internal imageState is updated.

import { openEditor } from './pintura.js';

const editor = openEditor({
    src: './my-image.jpeg',
});

editor.on('update', console.log);
// logs: { cropLimitToImage:…, cropMinSize:{…} , cropMaxSize:{…}, … }

processstart

Fired when an image starts processing.

processabort

Fired when image processing is aborted.

processerror

Fired when the image processing process throws an error.

processprogress

Fired when the image processing process makes progress.

process

Fired when the image has finished processing, receives the imageWriter output object.

import { openEditor } from './pintura.js';

const editor = openEditor({
    src: './my-image.jpeg',
});

editor.on('process', console.log);
// logs: { src:…, dest:… , imageState:…, store:… }

editor.process();

A list of events that are only used when the editor instance was created with the openEditor method.

show

Fired when the modal is shown.

hide

Fired when the modal is hidden.

close

Fired when the modal is closed using the top left close button.

Markup editor events

addshape

Fired when a shape is added in the editor.

editor.on('addshape', (shape) => {
    console.log('addshape', shape);
    // logs: { /* shape properties */ }
});

selectshape

Fired when a shape is selected in the editor.

editor.on('selectshape', (shape) => {
    console.log('selectshape', shape);
    // logs: { /* shape properties */ }
});

udpateshape

Fired when a shape is updated in the editor.

editor.on('updateshape', (shape) => {
    console.log('updateshape', shape);
    // logs: { /* shape properties */ }
});

removeshape

Fired when a shape is removed in the editor.

editor.on('removeshape', (shape) => {
    console.log('removeshape', shape);
    // logs: { /* shape properties */ }
});