Editor UI Exported Methods And Properties

The functions, properties, and defaults related to the editor UI that are exported by the Pintura module.

Locale
Editor
NodeTree

Locale

Export	Description
`locale_en_gb`	The English language configuration object for the Editor core.

The Markup editor and the editor Plugins export their own locale objects.

Other languages can be imported from the package/locale folder.

Editor exports

Factories

To create an editor instance use one of the following factory methods, note that this is only relevant when using JavaScript, the included framework adapters automatically handle this for us.

When using these methods we need to manually import plugins and other required editor dependencies.

Export	Description
`appendEditor(selector, options)`	Appends editor to the DOM and returns a single editor instance.
`appendEditors(selector, options)`	Appends multiple editors to the DOM and returns an array of editor instances.
`openEditor(options)`	Opens the editor in a modal.
`overlayEditor(selector, options)`	Overlays the editor UI on top of an image.
`defineCustomElements(options)`	Register the `<pintura-editor>` Custom Element.

openEditor

openEditor automatically creates a modal. It doesn't accept a selector or target element as the modal is added to the <body> element automatically.

The modal will automatically be shown when an image starts loading. Alternatively we can call the show and hide methods on the editor instance to manually show and hide the editor.

Please note that when we use openEditor instead of openDefaultEditor we need to import and set a list of required editor dependencies.

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

openEditor({
    src: 'image.jpeg',
    /* options here */
});

appendEditor

The appendEditor method can be used to create a single editor instance by either passing a selector or an element. Set second argument to an object to pass configuration values.

Please note that when we use appendEditor instead of appendDefaultEditor we need to import and set a list of required editor dependencies.

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

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

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

    appendEditor('.my-editor', {
        src: 'image.jpeg',
        /* options here */
    });
</script>

appendEditors

Use appendEditors to create multiple instances by either passing a NodeList, an Array, or a query selector. We can also add an extra object to pass configuration values. The configuration values are deep cloned and supplied to each instance.

Please note that when we use appendEditors instead of appendDefaultEditors we need to import and set a list of required editor dependencies.

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

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

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

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

    const editors = appendEditors('.my-editor', {
        src: 'image.jpeg',
        /* options */
    });
</script>

overlayEditor

Renders the editor with crop controls on top of the image. Useful for "in-place" editing of images. It functions the same as appendEditor.

Please note that when we use overlayEditor instead of overlayDefaultEditor we need to import and set a list of required editor dependencies.

When using this method, Pintura Image Editor will automatically:

Update the aspect ratio of the output image with the aspect ratio of the editor itself.
Zoom the preview image to fit the editor container
Disable the main menu.
Disable the crop preset dropdown.
Disable the crop info indicator.

The overlayEditor layout mode currently only supports showing the crop plugin.

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

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

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

    overlayEditor('.my-editor', {
        src: 'image.jpeg',
        /* options here */
    });
</script>

defineCustomElements

The defineCustomElements method makes it as easy as possible to define the <pintura-editor> element. When the returned Promise resolves the Custom Element is ready for use.

Note that in the <style> tag we target the Custom Element with the pintura-editor tag selector instead of the CSS class selector .pintura-editor.

Please note that when we use defineCustomElements instead of defineDefaultCustomElements we need to import and set a list of required editor dependencies.

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

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

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

    defineCustomElements({
        // Pass configuration options here
    }).then((elements) => {
        // Change configuration on individual elements
    });
</script>

The Custom Element dispatches events. To prevent collisions with default events each event Pintura Image Editor fires is prepended with 'pintura:'. This means that the 'load' event is called 'pintura:load'.

The Custom Element editor instances exposes the same properties, have the same methods, and fire the same events as the "normal" JavaScript instance. So this works as you would expect.

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

<script>
    // After the editor has been initialised
    const editor = document.querySelector('pintura-editor');

    // Change aspect ratio of image crop
    editor.imageCropAspectRatio = 1;
</script>

Default factories

The default editor factory methods below create a default editor, these factories are different from the normal factories in the following ways.

Automatically loads all plugins;
Sets the default locale to English.
Sets all default plugin options.
Hides the sticker plugin if no stickers are defined.
Sets the stickerStickToImage property to true.
Sets the shapePreprocessor property to the default shape preprocessors.
Accepts a configuration object for both the imageReader and imageWriter property. The factory will automatically pass the object to the internal createDefaultImageReader and createDefaultImageWriter calls.

If we need more fine grained control over which plugins are loaded, which locale is used, and which properties are set we need to use the non-default factory methods shown in the table above.

For documentation on the default factory methods please consult the respective non-default versions (openEditor for openDefaultEditor).

Note that this is only relevant when using JavaScript, the included framework adapters work with getEditorDefaults.

Export	Description
`getEditorDefaults(options)`	Sets default plugins, sets default locale, creates a default options object, merges in the passed options object and returns the resulting object. This method is used by all default shortcut methods in this table.
`appendDefaultEditor(selector, options)`	Sets default plugins, sets default locale, sets all default options, appends editor to the DOM and returns a single editor instance.
`appendDefaultEditors(selector, options)`	Sets default plugins, sets default locale, sets all default options, appends multiple editors to the DOM and returns an array of editor instances.
`openDefaultEditor(options)`	Sets default plugins, sets default locale, sets all default options, and opens the editor in a modal.
`overlayDefaultEditor(selector, options)`	Sets default plugins, sets default locale, sets all default options, overlays the editor UI on top of an image.
`defineDefaultCustomElements(options)`	Sets default plugins, sets default locale, sets all default options, registers the `<pintura-editor>` Custom Element.
`getCropperDefaults(options)`	A shortcut to create an image cropper. Functions the same as `getEditorDefaults` but returns a default cropper configuration.

openDefaultEditor

openDefaultEditor automatically creates a modal. It doesn't accept a selector or target element as the modal is added to the <body> element automatically.

The modal will automatically be shown when an image starts loading. Alternatively we can call the show and hide methods on the editor instance to manually show and hide the editor.

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

openDefaultEditor({
    src: 'image.jpeg',
    /* options here */
});

appendDefaultEditor

The appendDefaultEditor method can be used to create a single editor instance by either passing a selector or an element. Set second argument to an object to pass configuration values.

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

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

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

    appendDefaultEditor('.my-editor', {
        src: 'image.jpeg',
        /* options here */
    });
</script>

appendDefaultEditors

Use appendDefaultEditors to create multiple instances by either passing a NodeList, an Array, or a query selector. We can also add an extra object to pass configuration values. The configuration values are deep cloned and supplied to each instance.

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

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

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

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

    const editors = appendDefaultEditors('.my-editor', {
        src: 'image.jpeg',
        /* options */
    });
</script>

overlayDefaultEditor

Renders the editor with crop controls on top of the image. Useful for "in-place" editing of images. It functions the same as appendDefaultEditor.

When using this method, Pintura Image Editor will automatically:

Update the aspect ratio of the output image with the aspect ratio of the editor itself.
Zoom the preview image to fit the editor container
Disable the main menu.
Disable the crop preset dropdown.
Disable the crop info indicator.

The overlayEditor layout mode currently only supports cropping.

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

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

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

    overlayDefaultEditor('.my-editor', {
        src: 'image.jpeg',
        /* options here */
    });
</script>

getCropperDefaults

A helper method to quickly create an image cropper.

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

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

<script type="module">
    import { appendEditor, getCropperDefaults } from './pintura.js';

    appendEditor(
        '.my-editor',
        getCropperDefaults({
            src: 'image.jpeg',
            /* other options here */
        })
    );
</script>

See below how to use with various frameworks:

Helper methods

Export	Description
`setPlugins(...args)`	Registers the supplied plugins with Pintura Image Editor. Needs to be called before creating the editor.
`dispatchEditorEvents(editor, target)`	Dispatches the Pintura Image Editor events as Custom Events on the target element.
`colorStringToColorArray(str)`	Converts an RGB, RGBA, or HEX color string to a Color Array.
`degToRad(deg)`	Converts degrees to radians.
`blobToFile(blob, filename)`	Converts a `Blob` to a `File`.
`legacyDataToImageState(editorRef, imageSize, legacyDataObj)`	Converts a Pintura Image Editor legacy data object to an `imageState` object.
`isSupported()`	Returns `true` if the current browser supports Pintura Image Editor.
`supportsWebGL()`	Returns `true` if the current browser supports WebGL.

setPlugins

The editor uses plugins to render each util view, the setPlugins method lets us register the available plugins before the editor loads.

The factory methods below automatically register all available plugins, so we won't need setPlugins when using those.

getEditorDefaults
appendDefaultEditor
appendDefaultEditors
openDefaultEditor
overlayDefaultEditor
defineDefaultCustomElements

If we're not using one of the methods above we'll have to register our plugins with the setPlugins method before calling one of the other factory methods (appendEditor, openEditor, overlayEditor, etc.).

In the example below we'll load the crop plugin, the finetune plugin, and the annotate plugin.

import {
    // The method used to register the plugins
    setPlugins,

    // The plugins we want to use
    plugin_crop,
    plugin_finetune,
    plugin_annotate,
} from 'pintura.js';

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

colorStringToColorArray

Converts CSS colors to color arrays that can be parsed by the editor.

Accepts RGB, RGBA, and HEX values.

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

const shape = {
    backgroundColor: colorStringToColorArray('rgba(255, 0, 0, .5)'),
};

console.log(shape.backgroundColor);
// logs: [1, 0, 0, .5]

degToRad

Converts degrees to radians.

blobToFile

Converts a Blob to a File.

NodeTree exports

The NodeTree helper methods can be used to make interaction with internal node trees easier. These methods can be used with the willRenderToolbar, the willRenderShapeControls, and the willRenderShapePresetToolbar methods.

Export	Description
`createNode(type, id, props?, children?)`	Creates a new HTML element or component definition.
`findNode(id, parent)`	Finds a node object in a node list or another node.
`updateNode(node, props)`	Helper function to update the properties of a node.
`appendNode(node, parent)`	Appends a node to either a node list or to another node.
`removeNode(node, parent)`	Removes a node from a node list or another node.
`insertNodeBefore(node, id, parent)`	Inserts a node before the node with `id` in a node list or another node.
`insertNodeAfter(node, id, parent)`	Inserts a node before the node with `id` in a node list or another node.

createNode

The createNode function takes four parameters.

createNode(type, id, props, children);

The type should be either an HTML tag name (currently only 'div' is supported), a name of a Pintura component ('Button', 'Select', or 'Panel'), or a custom Svelte component.

The id argument should be set to a unique id.

The props argument can be set to an object with properties or attributes to set to the control. If the type argument is an HTML node name, the properties will be set as attributes on the created node. The textContent property is an exception to this, it will set the inner text of the created node (innerHTML is currently not supported).

The children argument can be set to an array of nodes. This argument is only available when the type argument is set to an HTML node name.

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

// Creating a <div> with text
const myDiv = createNode('div', 'my-div', {
    class: 'my-div-class',
    textContent: 'hi',
});

// Creating a Button component
const myNode = createNode('Button', 'my-button', {
    // The button label
    label: 'Hello world',
    // An optional button SVG icon
    icon: '<rect x="0" y="0" width="24" height="24" fill="red"/>',
    // A click event handler
    onclick: () => {
        /* do something here */
    },
});

// Creating a <div> with a Button inside it
const myDiv = createNode(
    'div',
    'my-div',
    {
        class: 'my-div-class',
        textContent: 'hi',
    },
    [createNode('Button', 'my-button', { label: 'Hello World' })]
);

Button

This example shows how to use the Button component.

openDefaultEditor({
    willRenderToolbar: (nodeList, env, redraw) => {
        // create your button
        const myNode = createNode('Button', 'my-button', {
            // the button label
            label: 'My label',

            // the button title
            title: 'My title',

            // an icon to add to the button
            icon: '<svg>',

            // is it disabled or not
            disabled: false,

            // when clicked what happens
            onclick: () => {
                console.log('do something');
            },
        });

        // find the container you want to add your node to
        const myContainer = findNode('beta', nodeList);

        // append the node to the container
        appendNode(myNode, myContainer);

        // done adjusting the nodelist
        return nodeList;
    },
});

Select

This example shows how to use the Select component.

openDefaultEditor({
    willRenderToolbar: (nodeList, env, redraw) => {
        // create your select
        const myNode = createNode('Select', 'my-select', {
            // the select label, optional, if omitted will show selected option label
            label: 'My label',

            // the select tooltip/title, optional
            title: 'My title',

            // which options to display when clicked
            options: [
                [0, 'First label'],
                [1, 'Second label'],
                [2, 'Third label'],
            ],

            // current index, optional, if omitted will use value
            selectedIndex: 1,

            // current value, optional, if omitted will use index 0
            value: 0,

            // handle selection change
            onchange: (item) => {
                console.log('do something with', item);
            },
        });

        // find the container you want to add your node to
        const myContainer = findNode('beta', nodeList);

        // append the node to the container
        appendNode(myNode, myContainer);

        // done adjusting the nodelist
        return nodeList;
    },
});

Panel

This example shows how to use the Panel component.

let myPanelNode = document.createElement('form');
myPanelNode.style.backgroundColor = 'orange';
myPanelNode.textContent = 'Hello world';

openDefaultEditor({
    willRenderToolbar: (nodeList, env, redraw) => {
        // create your panel
        const myNode = createNode('Panel', 'my-panel', {
            // the panel button label
            buttonLabel: 'My label',

            // the panel button title
            buttonTitle: 'My title',

            // the panel root element
            root: myPanelNode,
        });

        // find the container you want to add your node to
        const myContainer = findNode('beta', nodeList);

        // append the node to the container
        appendNode(myNode, myContainer);

        // done adjusting the nodelist
        return nodeList;
    },
});