v8.78.1

Search

Image properties

A list of properties to read from and write to the current state of the image loaded in the editor.

Readonly image properties

Property Description
imageFile The image source as a File object.
imageSize The natural size of the image.
imageLoadState The load state of the image.
imageProcessState The processing state of the image.
imageAspectRatio The aspect ratio of the image.
imageCropRectAspectRatio The aspect ratio of the crop rectangle.
imageCropSize The size of the crop rectangle.
imageRotationRange The min and max rotation of the image.

Loading and parsing of image data

Property Default value Description
src 
undefined
 The image source to load, can be of type File, Blob, DataURL, URL, ImageData, ImageBitmap, HTMLCanvasElement, or HTMLImageElement.
imageOrienter 
undefined
 The object to use to correctly orient preview image data.
imageReader 
undefined
 The imageReader to use for reading image data.
imageWriter 
undefined
 The imageWriter to use for writing image data.
imageScrambler 
undefined
 Used by redaction to scramble information in image layer.
imageRedactionRendering 
'pixelated'
 Set to 'auto' to have smooth blurring, currently not supported by Safari.
shapePreprocessor 
undefined
 The preprocessor used to render composit shapes like lineEnd styles and frames.

Image properties to update image state

Property Default value Description
imageCrop 
undefined
 A Rect describing the crop relative to the bounding box of the rotated image.
imageRotation 
0
 The rotation of the image in radians.
imageCropAspectRatio 
undefined
 Set the aspect ratio of the crop as a number.
imageCropLimitToImage 
true
 Set to true to limit the crop to the image edges.
imageCropMinSize 
{ width: 1, height: 1 }
 A Size describing The minimum size of the crop.
imageCropMaxSize 
{ width: 32768, height: 32768 }
 A Size describing The maximum size of the crop.
imageMinDuration 
0
 A minimum video duration in seconds.
imageMaxDuration 
Infinity
 A maximum video duration in seconds.
imageFlipX 
false
 Flip image over X axis.
imageFlipY 
false
 Flip image over Y axis.
imageTargetSize 
undefined
 A Size describing the output size of the image.
imageRedaction 
[]
 Set to an array of rectangle shapes to redact in the image.
imageAnnotation 
[]
 Set to an array of shapes to apply to the image.
imageDecoration 
[]
 Set to an array of shapes to apply to the crop.
imageManipulation 
[]
 An array of image manipulation shapes to apply to the image.
imageSelection 
[]
 An array of selection shapes to build a selection with.
imageFrame 
undefined
 Set to a frame shape or frame style name to draw on top of the output image.
imageBackgroundColor 
undefined
 A background color to render behind the output image, defaults to transparent. Will render black for non-transparent image formats.
imageBackgroundImage 
undefined
 The background image to render behind the output image.
imageColorMatrix 
undefined
 A color matrix to apply to the image.
imageGamma 
undefined
 The image gamma adjustment.
imageVignette 
undefined
 Vignette to apply to the image -1 to 1.
imageMetadata 
undefined
 Optional object to store custom metadata with the image.
imageState 
undefined
 The current state of the image, this contains all information to recreate the current image state.

imageFile

The image source as a File.

imageSize

The natural size of the currently loaded image, for example { width: 1024, height: 768 }.

imageLoadState

The imageLoadState contains the load state of the current image as it is passed through the imageReader.

imageProcessState

The imageProcessState contains the process state of the current image as it is passed through the imageWriter.

imageAspectRatio

The aspect ratio of the currently loaded image, for example 1 for a square image.

imageCropRectAspectRatio

The aspect ratio of the current crop rectangle, for example 1 for a square crop.

imageCropSize

The dimensions of the current crop rectangle, for example { width: 512, height: 512 } for a square crop.

imageRotationRange

The min an max rotation of the image, for example [-1, 1]

src

The source image to load. Update to load a new image.

Accepts:

  • File
  • Blob
  • DataURL
  • URL
  • ImageData
  • ImageBitmap
  • HTMLCanvasElement
  • HTMLImageElement

Due to browser security restrictions loading remote URLs is only possible if the remote location has properly configured CORS headers.

<!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 } from './pintura.js';

    const editor = appendDefaultEditor('#editor', { src: 'image.jpeg' });
</script>

imageOrienter

Can be set to a helper object to correctly orient image data. This is useful for older browsers where interpretation of the EXIF orientation header is done incorrectly and images appear upside down or mirrored.

The property expects an object with an read and an apply function.

  • The read function is used to read the EXIF orientation header from the image preview data.
  • The apply function is used to apply the EXIF orientation header to the image preview.

We can import the createDefaultImageOrienter method and use it to set the imageOrienter property to automatically orient images.

When using one of the default editor factories this property is set automatically.

<!DOCTYPE html>

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

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

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

<script type="module">
    import {
        appendEditor,
        createDefaultImageReader,
        createDefaultImageWriter,
        createDefaultImageOrienter,
        setPlugins,
        plugin_crop,
        locale_en_gb,
        plugin_crop_locale_en_gb,
    } from './pintura.js';

    setPlugins(plugin_crop);

    const editor = appendEditor('#editor', {
        imageReader: createDefaultImageReader(),
        imageWriter: createDefaultImageWriter(),
        imageOrienter: createDefaultImageOrienter(),
        locale: {
            ...locale_en_gb,
            ...plugin_crop_locale_en_gb,
        },
        src: 'image.jpeg',
    });
</script>

imageReader

Expects an array of read steps to step through when reading the src input image data.

We can import the createDefaultImageReader method and use it to set the imageReader property to read preview images.

<!DOCTYPE html>

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

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

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

<script type="module">
    import {
        appendEditor,
        createDefaultImageReader,
        createDefaultImageWriter,
        createDefaultImageOrienter,
        setPlugins,
        plugin_crop,
        locale_en_gb,
        plugin_crop_locale_en_gb,
    } from './pintura.js';

    setPlugins(plugin_crop);

    const editor = appendEditor('#editor', {
        imageReader: createDefaultImageReader({ orientImage: true }),
        imageWriter: createDefaultImageWriter(),
        imageOrienter: createDefaultImageOrienter(),
        locale: {
            ...locale_en_gb,
            ...plugin_crop_locale_en_gb,
        },
        src: 'image.jpeg',
    });
</script>

The imageReader property has to be set for the editor to be able to show image previews, without it the editor won't run.

When using the default editor factories we don't have to set this property as it's set automatically.

If we want to pass different configuration options we can set them to the property directly.

<!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 } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        imageReader: { orientImage: true },
    });
</script>

imageWriter

Expects an array of write steps to step through when writing the output image data.

We can import the createDefaultImageWriter method and use it to set the imageWriter property to write output images.

<!DOCTYPE html>

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

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

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

<script type="module">
    import {
        appendEditor,
        createDefaultImageReader,
        createDefaultImageWriter,
        createDefaultImageOrienter,
        setPlugins,
        plugin_crop,
        locale_en_gb,
        plugin_crop_locale_en_gb,
    } from './pintura.js';

    setPlugins(plugin_crop);

    const editor = appendEditor('#editor', {
        imageReader: createDefaultImageReader(),
        imageWriter: createDefaultImageWriter({ quality: 0.5 }),
        imageOrienter: createDefaultImageOrienter(),
        locale: {
            ...locale_en_gb,
            ...plugin_crop_locale_en_gb,
        },
        src: 'image.jpeg',
    });
</script>

If we don't need to output image data, for example when we're only storing the original image and the editor state, we don't have to set the imageWriter property.

When using the default editor factories we don't have to set this property as it's automatically defined.

If we want to pass different configuration options we can set them to the property directly.

<!DOCTYPE html>

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

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

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

<script type="module">
    import {
        appendEditor,
        createDefaultImageReader,
        createDefaultImageOrienter,
        setPlugins,
        plugin_crop,
        locale_en_gb,
        plugin_crop_locale_en_gb,
    } from './pintura.js';

    setPlugins(plugin_crop);

    const editor = appendEditor('#editor', {
        imageReader: createDefaultImageReader(),
        imageWriter: { quality: 0.5 },
        imageOrienter: createDefaultImageOrienter(),
        locale: {
            ...locale_en_gb,
            ...plugin_crop_locale_en_gb,
        },
        src: 'image.jpeg',
    });
</script>

imageScrambler

Set to a function that can receive an ImageData or ImageBitmap object, should return scrambled ImageData or an HTMLCanvasElement. Used with the imageRedaction property and createDefaultImageScrambler function to redact information in an image.

<!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 } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        imageScrambler: (data) =>
            new Promise((resolve) => {
                // Receives current image as ImageData or ImageBitmap

                // Blur here, advise is to return an image with smaller dimensions

                // Resolves with blurred ImageData or HTMLCanvasElement
                resolve(imageData);
            }),
    });
</script>

We can import the createDefaultImageScrambler function and use it to set the imageScrambler property to handle scrambling the image data for us.

<!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,
        createDefaultImageScrambler,
    } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        imageScrambler: createDefaultImageScrambler({ scrambleAmount: 2 }),
    });
</script>

When using the default editor factories we don't have to set this property as it's automatically defined.

If we want to pass different configuration options we can set them to the property directly.

<!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 } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        imageScrambler: { scrambleAmount: 2 },
    });
</script>

shapePreprocessor

The preprocessor used to render composit shapes like lineEnd styles and frames. Use createDefaultShapePreprocessor to set the default preprocessor.

Use createShapePreprocessor to create a custom shape preprocessor.

When using the default editor factories we don't have to set this property as it's automatically defined. We can however set it to a custom shape preprocessor which will then automatically be added to the shape preprocessor list.

If we don't use lineEnd styles and frame styles we don't need a shapePreprocessor and we can leave this property undefined.

<!DOCTYPE html>

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

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

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

<script type="module">
    import {
        appendEditor,
        createDefaultImageReader,
        createDefaultImageWriter,
        createDefaultImageOrienter,
        createDefaultShapePreprocessor,
        setPlugins,
        plugin_crop,
        locale_en_gb,
        plugin_crop_locale_en_gb,
    } from './pintura.js';

    setPlugins(plugin_crop);

    const editor = appendEditor('#editor', {
        imageReader: createDefaultImageReader(),
        imageWriter: createDefaultImageWriter(),
        imageOrienter: createDefaultImageOrienter(),
        locale: {
            ...locale_en_gb,
            ...plugin_crop_locale_en_gb,
        },
        src: 'image.jpeg',
        shapePreprocessor: createDefaultShapePreprocessor(),
    });
</script>

Adding a custom shape preprocessor when using one of the default factories. See createShapePreprocessor for the function signature.

<!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 } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        shapePreprocessor: [
            // custom shape preprocessor
            (shape, options) => {
                // process shape here
            },

            // another custom shape preprocessor
        ],
    });
</script>

imageCrop

The current crop rectangle is relative to the (optionally rotated) bounding box of the image.

In the diagram below we can see how this works. We've defined a 64 x 64 crop in the top left corner of the image.

  • The dashed line illustrates the bounding box of the rotated image.
  • The magenta square represents our 64 × 64 crop positioned relative to the image bounding box.

We can see how the crop rectangle updates when we rotate the image using the range input.

If we assign options to the editor creation command the crop will be set first and then the rotation. In the example below, no matter the order of the properties, the crop will be set first and then the image will be rotated.

<!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, degToRad } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',

        // 2. Rotate the image
        imageRotation: degToRad(45),

        // 1. Crop 64 x 64 image from top left corner
        imageCrop: {
            x: 0,
            y: 0,
            width: 64,
            height: 64,
        },
    });
</script>

imageRotation

The rotation of the image in radians. Use the degToRad export to set this property in degrees.

<!DOCTYPE html>

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

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

<button type="button" id="buttonRotateImage">Rotate image</button>

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

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

    const buttonRotateImage = document.querySelector('#buttonRotateImage');

    const editor = appendDefaultEditor('#editor', { src: 'image.jpeg' });

    buttonRotateImage.addEventListener('click', () => {
        editor.imageRotation += Math.PI / 4;
    });
</script>

imageCropAspectRatio

Set the aspect ratio of the crop as a number.

When not set, it defaults to undefined meaning a crop aspect ratio won't be enforced.

<!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 } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',

        // Enforce widescreen 16:9 aspect ratio
        imageCropAspectRatio: 16 / 9,
    });
</script>

imageCropMinSize

A Size describing The minimum size of the crop. Defaults to { width: 1, height: 1 }. Pintura will prevent loading smaller images.

imageCropMaxSize

A Size describing The maximum size of the crop. Defaults to { width: 32768, height: 32768 }.

imageFlipX

Flip image over X axis.

<!DOCTYPE html>

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

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

<button type="button" id="buttonFlipImage">Flip image</button>

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

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

    const buttonFlipImage = document.querySelector('#buttonFlipImage');

    const editor = appendDefaultEditor('#editor', { src: 'image.jpeg' });

    buttonFlipImage.addEventListener('click', () => {
        editor.imageFlipX = !editor.imageFlipX;
    });
</script>

imageFlipY

Flip image over Y axis.

<!DOCTYPE html>

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

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

<button type="button" id="buttonFlipImage">Flip image</button>

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

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

    const buttonFlipImage = document.querySelector('#buttonFlipImage');

    const editor = appendDefaultEditor('#editor', { src: 'image.jpeg' });

    buttonFlipImage.addEventListener('click', () => {
        editor.imageFlipY = !editor.imageFlipY;
    });
</script>

imageTargetSize

A size describing the output size of the image, this value is visible in the Resize plugin input fields. Use the targetSize property on the imageWriter to set a size invisible to the user.

imageCropLimitToImage

Defaults to true, when set to true Pintura Image Editor will prevent cropping outside of

When set to false we can make a crop outside of the image edges. This also means we can zoom out further and rotate the image without auto zoom. To control the background color of pixels outside of the image we can set the imageBackgroundColor prop.

imageRedaction

Set to an array of rectangular shapes to redact parts of the image. If the image is rotated or flipped, the redactions rotate and flip with the image.

See the updating shapes section on how to add, remove or update redaction shapes.

imageAnnotation

Set to an array of shapes to draw them in the image context. If the image is rotated or flipped, the shapes rotate and flip with the image.

See the updating shapes section on how to add, remove or update shapes.

imageDecoration

Set to an array of shapes to draw them in the crop context. If the image is rotated or flipped, the shapes stay where they are. If the crop rectangle is changed, the shape positions are updated as well.

See the updating shapes section on how to add, remove or update shapes.

imageFrame

Can be set to a frameStyle to select an initial frame style.

When using frames we need to set the shapePreprocessor property, either set the defaults or define your own custom frame styles.

<!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 } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        imageFrame: {
            // the key of the frame in the menu
            id: 'polaroid',

            // the style of the frame
            frameStyle: 'polaroid',

            // current style properties
            frameColor: [1, 1, 1],
        },
    });
</script>

imageColorMatrix

A color matrix to apply to the image. The imageColorMatrix property contains multiple color matrices for both the filter settings and finetune color settings.

To set a custom color matrix, assign it like shown below.

<!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 } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        imageColorMatrix: {
            // prettier-ignore
            filter: [
                    0.75, 0.25, 0.25, 0, 0,
                    0.25, 0.75, 0.25, 0, 0,
                    0.25, 0.25, 0.75, 0, 0,
                    0,    0,    0,    1, 0
                ],
        },
    });
</script>

imageBackgroundColor

Set the background color to use for the output image and the image preview in the editor.

<!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 } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        imageBackgroundColor: [1, 0, 0],
    });
</script>

If we like a more familiar way of setting colors we can use the colorStringToColorArray method exported by the Pintura Image Editor module.

<!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, colorStringToColorArray } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        imageBackgroundColor: colorStringToColorArray('rgba(255, 0, 0, .5)'),
    });
</script>

Transparent background colors are supported for the output image but at the moment the image rendering in the editor itself isn't fully accurate.

imageBackgroundImage

Set to a background image to render behind the crop. Accepts the same source types as the image src property.

The image will be centered and scaled to cover the output image dimensions.

imageMinDuration

The minimum required duration for video files.

Will be renamed to mediaMinDuration in the next major release.

imageMaxDuration

The maximum required duration for video files. This will not prevent loading longer files, the Trim plugin will prevent outputing longer files by limiting the clip length.

Will be renamed to mediaMaxDuration in the next major release.

imageState

The imageState property describes the current image state.

You can pass the imageState object to the loadImage method or store it and later use it to set the imageState to restore a previous state. The imageState is also returned after processing an image.

An example imageState object is shown below.

{
    // transforms
    flipX: false,
    flipY: false,
    rotation: 0,
    crop: { x: 0, y: 0, width: 1024, height: 768 },
    cropAspectRatio: undefined,
    cropMinSize: { width: 1, height: 1 },
    cropMaxSize: { width: 32767, height: 32767 },
    cropLimitToImage: true,

    // shapes
    annotation: [
        {
            id: 'lme6159vp',
            x: 32,
            y: 64,
            width: 320,
            height: 256,
            backgroundColor: [1, 0, 0],
            strokeColor: [1, 1, 1, 0],
            strokeWidth: 0,
            cornerRadius: 0,
        }
    ],
    decoration: [],
    manipulation: [],
    redaction: [],
    selection: [],
    frame: undefined,

    // filters
    colorMatrix: undefined,
    convolutionMatrix: undefined,
    gamma: undefined,
    vignette: undefined,

    // output
    backgroundColor: [0, 0, 0, 0],
    backgroundImage: undefined,
    targetSize: undefined,

    // custom
    metadata: undefined,

    // video
    trim: undefined,
    volume: 1,
    minDuration: 0,
    maxDuration: undefined,
    currentTime: undefined
}