v8.95.3

Search

Editor UI Exported Methods And Properties

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

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.

<!DOCTYPE html>

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

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

<div id="editor"></div>

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

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        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,

                // set to true to hide the label
                hideLabel: false,

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

                    // if you updated state outside of the editor, run redraw() to redraw the toolbar
                    redraw();
                },
            });

            // 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;
        },
    });
</script>

Select

This example shows how to use the Select component.

<!DOCTYPE html>

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

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

<div id="editor"></div>

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

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        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);

                    // if you updated state outside of the editor, run redraw() to redraw the toolbar
                    redraw();
                },
            });

            // 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;
        },
    });
</script>

Panel

This example shows how to use the Panel component.

The panel will autoclose when escape is pressed or the user clicks outside of the panel. If you want to hide the panel you can set the isActive property to false. The onshow, and onhide callbacks can be used to sync the current panel state.

<!DOCTYPE html>

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

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

<div id="editor"></div>

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

    let myPanelNode = document.createElement('textarea');

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        willRenderToolbar: (nodeList, env, redraw) => {
            // So we can browse through the nodes in the developer console
            console.log(nodeList);

            // 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, in this case our textarea
                root: myPanelNode,

                // panel is visible
                onshow: () => {
                    console.log('panel visible');

                    // if you updated state outside of the editor, run redraw() to redraw the toolbar
                    redraw();
                },

                // panel is hidden
                onhide: () => {
                    console.log('panel hidden');
                },
            });

            // 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;
        },
    });
</script>

appendNode

Adds a node to a nodeList.

<!DOCTYPE html>

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

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

<div id="editor"></div>

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

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        willRenderToolbar: (nodeList) => {
            // So we can browse through the nodes in the developer console
            console.log(nodeList);

            // Adds a node to the end of the nodeList
            appendNode(
                createNode('div', 'my-div', {
                    textContent: 'Hello World',
                }),
                nodeList
            );

            return nodeList;
        },
    });
</script>

findNode

Finds a node in a nodeList. In the example below we set the label property, we can do this more easily with the updateNode function.

<!DOCTYPE html>

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

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

<div id="editor"></div>

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

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        willRenderToolbar: (nodeList) => {
            // So we can browse through the nodes in the developer console
            console.log(nodeList);

            // Find the export button
            const exportButton = findNode('export', nodeList);

            // Replace the label
            exportButton[2].label = 'Save';

            // Always show the label
            exportButton[2].hideLabel = false;

            return nodeList;
        },
    });
</script>

updateNode

A helper function to update the properties of a node. We find the node we need using findNode and then update one ore more of its properties.

<!DOCTYPE html>

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

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

<div id="editor"></div>

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

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        willRenderToolbar: (nodeList) => {
            // So we can browse through the nodes in the developer console
            console.log(nodeList);

            // Find the export button
            const exportButton = findNode('export', nodeList);

            // Update the save property
            updateNode(exportButton, { label: 'Save', hideLabel: false });

            return nodeList;
        },
    });
</script>

removeNode

A helper function to remove nodes from the node list.

<!DOCTYPE html>

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

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

<div id="editor"></div>

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

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        willRenderToolbar: (nodeList) => {
            // So we can browse through the nodes in the developer console
            console.log(nodeList);

            // Remove the export button
            removeNode('export', nodeList);

            return nodeList;
        },
    });
</script>