Setting up Pintura Image Editor with React

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

It includes a normal, modal, and overlay editor example, as well as an example showing how to integrate FilePond with Pintura.

Installing the React modules

Using test version

Test versions of the pintura and react-pintura modules are available on NPM.

npm install --save @pqina/react-pintura @pqina/pintura

Using private npm

The pintura module is available on the pqina private npm.

In our project root directory we create a file called .npmrc and copy the snippet below to the file. Then we replace PQINA_NPM_KEY with our private npm key as displayed on the pqina customer portal.

@pqina:registry=https://npm.pqina.nl/
//npm.pqina.nl/:_authToken=PQINA_NPM_KEY

Now we can install the needed modules like shown below.

npm install --save @pqina/react-pintura @pqina/pintura

Using local modules

Instead of installing from the private npm we can create a local_modules folder inside our project root directory. We then copy paste the pintura files from the product package, the react-pintura package is available on npm.

We can now install the modules like shown below.

npm install --save @pqina/react-pintura ./local_modules/pintura

Default React implementation example

In the default example below we'll use the getEditorDefaults 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.

// Import the editor styles
import '@pqina/pintura/pintura.css';

// Import the editor default configuration
import { getEditorDefaults } from '@pqina/pintura';

// Import the editor component from `react-pintura`
import { PinturaEditor } from '@pqina/react-pintura';

// get default properties
const editorConfig = getEditorDefaults();

function App() {
    return (
        <div className="App" style={{ height: '600px' }}>
            <PinturaEditor
                {...editorConfig}
                src="image.jpeg"
                imageCropAspectRatio={1}
            ></PinturaEditor>
        </div>
    );
}

export default App;

React Events and properties

To handle events we can use camelcase props. This means that to listen for the Pintura Image Editor load event we have to set the onLoad prop.

<PinturaEditor onLoad={handleEvent} />

Properties can be used as we would with the normal JavaScript version of the editor.

<PinturaEditor src="image.jpeg" />

React Methods

To run editor methods we need to get a ref to the editor component. We can do so using the useRef hook. When the reference is set up we can access the editor instance.

export default function Example() {
    // get a reference to the PinturaEditor component
    const componentRef = useRef(null);

    const handleUndo = () => {
        // get reference to editor instance
        const { editor } = componentRef.current;

        // run history.undo()
        editor.history.undo();
    };

    return (
        <div className="App">
            <button onClick={handleUndo}>Undo</button>

            <div style={{ height: '600px' }}>
                <PinturaEditor ref={componentRef} src={'image.jpeg'} />
            </div>
        </div>
    );
}

Advanced React 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.

// Import the editor styles
import '@pqina/pintura/pintura.css';

// Import the editor functionality
import {
    // Import the default image reader and writer
    createDefaultImageReader,
    createDefaultImageWriter,

    // The method used to register the plugins
    setPlugins,

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

    // The user interface 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 configuration for the markup editor and finetune plugins
    markup_editor_defaults,
    plugin_finetune_defaults,
} from '@pqina/pintura';

// Import the editor component from `react-pintura`
import { PinturaEditor } from '@pqina/react-pintura';

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

// Create our editor configuration
const editorConfig = {
    // This will read the image data (required)
    imageReader: createDefaultImageReader(),

    // This will write the output image
    imageWriter: createDefaultImageWriter(),

    // The markup editor default options, tools, shape style controls
    ...markup_editor_defaults,

    // The finetune util controls
    ...plugin_finetune_defaults,

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

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

    // The icons and labels to use in the user interface (required)
    locale: {
        ...locale_en_gb,
        ...plugin_crop_locale_en_gb,
        ...plugin_finetune_locale_en_gb,
        ...plugin_annotate_locale_en_gb,
        ...markup_editor_locale_en_gb,
    },
};

function App() {
    return (
        <div className="App" style={{ height: '600px' }}>
            <PinturaEditor
                {...editorConfig}
                src="image.jpeg"
                imageCropAspectRatio={1}
            ></PinturaEditor>
        </div>
    );
}

export default App;

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