v8.89.6

Search

Frame plugin

The Frame plugin enables us to add controls to update the frame drawn on top of the image.

We can import the default frame control set or define our own styles.

Property Default value Description
frameStyles 
undefined
 An object describing the available frame styles.
frameOptions 
undefined
 A list of key label pairs describing which frame styles to render in the menu.

frameStyles

An object describing the styles of the frame shapes and the HTML or SVG to use when drawing their thumbnails.

<!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',
        frameStyles: {
            solidSharp: {
                shape: {
                    frameStyle: 'solid',
                    frameSize: '2.5%',
                },
                thumb: '<rect stroke-width="5" x="0" y="0" width="100%" height="100%"/>',
            },
            solidRound: {
                shape: {
                    frameStyle: 'solid',
                    frameSize: '2.5%',
                    frameRound: true,
                },
                thumb: '<rect stroke-width="5" x="0" y="0" width="100%" height="100%" rx="12%"/>',
            },
            lineSingle: {
                shape: {
                    frameStyle: 'line',
                    frameInset: '2.5%',
                    frameSize: '.3125%',
                    frameRadius: 0,
                },
                thumb: '<div style="top:.5em;left:.5em;right:.5em;bottom:.5em;box-shadow:inset 0 0 0 1px currentColor"></div>',
            },
        },
    });
</script>

frameOptions

A list of key label pairs describing which frame styles to render. Label can be a string but in most cases is a function, the function is then passed the current locale and can select the correct locale key.

<!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',
        frameOptions: [
            // No frame
            [undefined, (locale) => locale.labelNone],

            // Sharp edge frame
            ['solidSharp', (locale) => locale.frameLabelMatSharp],

            // Rounded edge frame
            ['solidRound', (locale) => locale.frameLabelMatRound],

            // A single line frame
            ['lineSingle', (locale) => locale.frameLabelLineSingle],
        ],
    });
</script>

Frame plugin exports

The core editor module exports the following Frame plugin objects.

Export Description
plugin_frame The frame util view.
plugin_frame_defaults A default frame util configuration object exposing a selection of the frame styles below.
plugin_frame_locale_en_gb The frame util locales.
frameSolidSharp An inset edge.
frameSolidRound A rounded inset edge.
frameLineSingle A single line inset.
frameLineMultiple A multi line inset.
frameEdgeSeparate Lines separated along image edges.
frameEdgeCross Lines crossed at corners of image.
frameEdgeOverlap Lines slightly overlapping at image corners.
frameHook Hooks drawn in corners of image.
framePolaroid A Polaroid style frame, best used with Polaroid aspect ratio 0.973

Adding a custom frame style

import { openDefaultEditor, plugin_frame_defaults } from '@pqina/pintura';

// get defaults
const { frameOptions, frameStyles } = plugin_frame_defaults;

// create editor
const editor = openDefaultEditor({
    src: 'test.jpeg',

    // Show frame util
    util: 'frame',

    // select our custom frame
    imageFrame: {
        id: 'myFrame',
        frameStyle: 'my-custom-frame',
        frameColor: [1, 0, 0],
    },

    // These are the options in the frame list
    frameOptions: [
        // Default frame options
        ...frameOptions,

        // Custom 'myFrame'
        ['myFrame', 'My Frame'],
    ],

    // These are the styles available
    frameStyles: {
        // Default styles
        ...frameStyles,

        // Our custom frame style
        myFrame: {
            // The default shape styles for our frame
            shape: {
                frameStyle: 'my-custom-frame',
                frameColor: [1, 0, 0],
            },

            // The thumbnail to show in the toolbar
            thumb: '<rect stroke-width="5" x="0" y="0" width="100%" height="100%"/>',
        },
    },

    // The shape preprocessor expands shapes to more shapes, we can only use pixel values in the shape preprocessor
    shapePreprocessor: [
        // Our custom shape preprocessor
        (shape, options) => {
            // Should return undefined if shape is not a match
            if (shape.frameStyle !== 'my-custom-frame') return;

            // offset from edge, used by the line shape below
            const f = Math.max(shape.width, shape.height) * 0.05;

            return [
                // Overlay a rectangle with a background image
                {
                    x: 0,
                    y: 0,
                    width: shape.width,
                    height: shape.height,

                    // We overlay a transparent png
                    backgroundImage: 'my-image.png',
                },
                // Overlay a line on the inside of the image
                {
                    x: f,
                    y: f,
                    width: shape.width - f * 2,
                    height: shape.height - f * 2,
                    strokeWidth: 2,

                    // Use shape property as style
                    strokeColor: shape.frameColor,
                },
                // Add other shapes if needed
                // ...
            ];
        },
    ],
});