Setting up Pintura Image Editor with Uppy

For a quick start use the Uppy example project as a guideline.

To set up the editor with Uppy we use the useEditorWithUppy plugin which is included in the product package.

Please note that Uppy doesn't currently support editing remote files, so Pintura won't be able to edit images provided by Uppy Companion plugins.

Before continuing it's highly recommended to read the JavaScript installation guide as it clarifies important internal functionality of the image editor.

Default implementation example

In the default example below we'll use the openDefaultEditor method to quickly create an image editor.

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>

<!-- Uppy styles -->
<link
    rel="stylesheet"
    href="https://transloadit.edgly.net/releases/uppy/v1.8.0/uppy.min.css"
/>

<!-- Pintura Image Editor styles -->
<link rel="stylesheet" href="./pintura/pintura.css" />

<!-- Uppy field -->
<div id="drag-drop-area"></div>

<!-- Uppy scripts -->
<script src="https://transloadit.edgly.net/releases/uppy/v1.8.0/uppy.min.js"></script>

<!-- Pintura Image Editor plugin -->
<script src="./useEditorWithUppy-iife.js"></script>

<script type="module">
    // import Pintura Image Editor functionality
    import { openDefaultEditor } from './pintura/pintura.js';

    // Create Uppy instance
    const uppy = Uppy.Core({
        onBeforeFileAdded: useEditorWithUppy(
            // Method used to create Pintura Image Editor
            openDefaultEditor,

            // The editor options
            {
                imageCropAspectRatio: 1,
            },

            // Reference to Uppy addFile API
            () => uppy.addFile
        ),
    })
        .use(Uppy.Dashboard, { inline: true, target: '#drag-drop-area' })
        .use(Uppy.Tus, { endpoint: 'https://master.tus.io/files/' });
</script>

Advanced implementation example

In this example we'll create a custom editor, using a custom set of plugins, locale, and available options.

While this example is a lot more verbose it does allow us to create a more optimal editor package. The build process will tree-shake unused functionality resulting in a smaller build target.

<!DOCTYPE html>

<!-- Uppy styles -->
<link
    rel="stylesheet"
    href="https://transloadit.edgly.net/releases/uppy/v1.8.0/uppy.min.css"
/>

<!-- Pintura Image Editor styles -->
<link rel="stylesheet" href="./pintura/pintura.css" />

<!-- Uppy field -->
<div id="drag-drop-area"></div>

<!-- Uppy scripts -->
<script src="https://transloadit.edgly.net/releases/uppy/v1.8.0/uppy.min.js"></script>

<!-- Pintura Image Editor plugin -->
<script src="./useEditorWithUppy-iife.js"></script>

<script type="module">
    // import Pintura Image Editor modules
    import {
        // Image editor
        openEditor,
        createDefaultImageReader,
        createDefaultImageWriter,

        // The plugins we want to use
        plugin_crop,
        plugin_finetune,
        plugin_annotate,

        // The main UI 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 properties
        markup_editor_defaults,
        plugin_finetune_defaults,
    } from './pintura/pintura.js';

    setPlugins(plugin_crop, plugin_finetune, plugin_annotate);

    // Create Uppy instance
    const uppy = Uppy.Core({
        onBeforeFileAdded: useEditorWithUppy(
            // Method used to create Pintura Image Editor
            openEditor,

            // Pintura Image Editor editor options
            {
                imageReader: createDefaultImageReader(),
                imageWriter: createDefaultImageWriter(),

                // Set Markup Editor defaults
                ...markup_editor_defaults,

                // Set Finetune plugin defaults
                ...plugin_finetune_defaults,

                // This handles complex shapes like arrows / frames
                shapePreprocessor: createDefaultShapePreprocessor(),

                // This will set a square crop aspect ratio
                imageCropAspectRatio: 1,

                // Set locale
                locale: {
                    ...locale_en_gb,
                    ...plugin_crop_locale_en_gb,
                    ...plugin_finetune_locale_en_gb,
                    ...plugin_annotate_locale_en_gb,
                    ...markup_editor_locale_en_gb,
                },
            },

            // Reference to Uppy addFile API
            () => uppy.addFile
        ),
    })
        .use(Uppy.Dashboard, { inline: true, target: '#drag-drop-area' })
        .use(Uppy.Tus, { endpoint: 'https://master.tus.io/files/' });
</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