Using the Pintura Image Editor Custom Element

The Pintura Image Editor Custom Element helper method allow easy use via the DOM api.

Default

In the default example below we'll use the defineDefaultCustomElements method to quickly register a default <pintura-editor> custom 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.css" />

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

<pintura-editor src="./my-image.jpeg"></pintura-editor>

<script type="module">
    import { defineDefaultCustomElements } from 'pintura.js';

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

Events and Properties

To listen for events we can use addEventListener. We prefix all default events with pintura:. This means that to listen for the Pintura Image Editor load event we have to listen for the pintura:load event.

<!-- copy -->
<pintura-editor src="my-image.jpeg"></pintura-editor>
<script>
    // get reference to editor element
    const editor = document.querySelector('pintura-editor');

    // listen for load event
    editor.addEventListener('pintura:load', (e) => {
        console.log(e.detail);
        // logs: { src:…, dest:… , size:… }
    });
</script>

Properties can be used as we would with the normal JavaScript version of the editor, each <pintura-editor> element has the same properties as an editor instance.

<!-- copy -->
<pintura-editor src="my-image.jpeg"></pintura-editor>
<script>
    // get reference to editor element
    const editor = document.querySelector('pintura-editor');

    // set property
    editor.imageCropAspectRatio = 1;
</script>

Advanced

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 appendEditor 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.css" />

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

<pintura-editor src="./my-image.jpeg"></pintura-editor>

<script type="module">
    import {
        // The editor factory method
        defineCustomElements,

        // Import 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
        markup_editor_locale_en_gb,

        // Import the default configuration for the markup editor and finetune plugins
        markup_editor_defaults,
        plugin_finetune_defaults,
    } from 'pintura.js';

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

    // This will initialise all <pintura-editor> custom elements with the passed options
    defineCustomElements({
        // 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 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 configuration options