Volto Image Editor (@plone-collective/volto-image-editor)

An image editor, based on React Advanced Image Cropper, to be used with Plone and Volto.

✨ Features

This add-on modifies Volto's File widget, providing an image editor with the following actions:

• Crops the image. Supports many aspect ratios
• Rotates the image in 90-degree increments
• Flips the image horizontally or vertically
• Adjusts the image saturation
• Adjusts the image brightness
• Adjusts the image contrast
• Adjusts the image hue

🚀 Installation

Note: This add-on requires Volto 18 or newer. Follow your project's official workflow for dependency management.

To install this add-on, edit the package.json of your policy package (usually located in packages/<policy-package>/package.json):

"addons": [
    "@plone-collective/volto-image-editor"
],
"dependencies": {
    "@plone-collective/volto-image-editor": "*"
}

After editing, follow your project's standard process to update dependencies and rebuild.

⚙️ Configure Default Settings

This add-on allows you to customize the image editor's behavior by modifying default settings. All settings are optional and can be configured in your Volto project's add-on configuration.

Available Settings

The following table describes all available settings for the image editor:

| Setting | Description | Type | Default Value | |---------|-------------|------|----------------| | aspectRatio | The aspect ratio constraint for cropping (width:height format) | string | '16:9' | | imageRestriction | How the image should be restricted within the crop area | string | 'fit-area' | | stencilType | The shape of the crop stencil/box | string | 'rectangle' | | minWidth | Minimum width for the crop area in pixels | number | 50 | | minHeight | Minimum height for the crop area in pixels | number | 50 | | maxCropWidth | Maximum width for the crop area in pixels | undefined \| number | undefined | | maxCropHeight | Maximum height for the crop area in pixels | undefined \| number | undefined | | scalable | Whether the image can be scaled/zoomed | boolean | true | | stencilGrid | Whether to display a grid overlay on the crop stencil | boolean | true | | minScale | Minimum scale factor for zooming | number | 0.1 | | maxScale | Maximum scale factor for zooming | number | 3 |

Configuration Examples

Single Setting Modification

To modify a single setting, update config.settings.imageEditor in your add-on's configuration file:

import type { ConfigType } from '@plone/registry';

function applyConfig(config: ConfigType) {
  // Modify the default aspect ratio to 1:1
  config.settings.imageEditor.aspectRatio = '1:1';

  return config;
}

export default applyConfig;

Multiple Settings Modification

If you need to modify multiple settings, we recommend using the ImageSettings type definition for type safety and better code documentation:

import type { ConfigType } from '@plone/registry';
import type { ImageSettings } from '@plone-collective/volto-image-editor/types/ImageSettings';

function applyConfig(config: ConfigType) {
  // Define your custom image editor settings
  const imageEditorSettings: ImageSettings = {
    aspectRatio: '1:1',
    imageRestriction: 'fit-area',
    stencilType: 'rectangle',
    minWidth: 100,
    minHeight: 100,
    maxCropWidth: undefined,
    maxCropHeight: undefined,
    scalable: true,
    stencilGrid: true,
    minScale: 0.1,
    maxScale: 3,
  };

  // Apply the custom settings
  config.settings.imageEditor = imageEditorSettings;

  return config;
}

export default applyConfig;

🧪 Test Installation

Visit http://localhost:3000/ in a browser, log in, and verify that the image editor features are available in the File widget.

🌍 Internationalization (i18n)

All UI strings in this add-on are translatable. Use the provided make i18n command to extract and sync translation messages.

🛠️ Development

Development for this add-on uses pnpm workspaces, the latest mrs-developer, and Volto core improvements. It is compatible only with pnpm and Volto 18.

📋 Prerequisites

• An operating system that runs all the requirements mentioned.
• nvm
• Node.js and pnpm 22
• Make
• Git
• Docker (optional)

📦 Installation

1. Clone this repository, then change your working directory.

   git clone [email protected]:collective/volto-image-editor.git
   cd volto-image-editor

2. Install this code base.

   make install

🧰 Make Convenience Commands

Run make help to list the available commands.

help                             Show this help
install                          Installs the add-on in a development environment
start                            Starts Volto, allowing reloading of the add-on during development
build                            Build a production bundle for distribution of the project with the add-on
i18n                             Sync i18n
ci-i18n                          Check if i18n is not synced
format                           Format codebase
lint                             Lint, or catch and remove problems, in code base
release                          Release the add-on on npmjs.org
release-dry-run                  Dry-run the release of the add-on on npmjs.org
test                             Run unit tests
ci-test                          Run unit tests in CI
backend-docker-start             Starts a Docker-based backend for development
storybook-start                  Start Storybook server on port 6006
storybook-build                  Build Storybook
acceptance-frontend-dev-start    Start acceptance frontend in development mode
acceptance-frontend-prod-start   Start acceptance frontend in production mode
acceptance-backend-start         Start backend acceptance server
ci-acceptance-backend-start      Start backend acceptance server in headless mode for CI
acceptance-test                  Start Cypress in interactive mode
ci-acceptance-test               Run cypress tests in headless mode for CI

🏗️ Development Environment Setup

Install package requirements:

make install

🚦 Start Developing

Start the backend:

make backend-docker-start

In a separate terminal session, start the frontend:

make start

🧹 Lint Code

Run ESLint, Prettier, and Stylelint in analyze mode:

make lint

🎨 Format Code

Run ESLint, Prettier, and Stylelint in fix mode:

make format

🌍 Internationalization (i18n)

Extract the i18n messages to locales:

make i18n

🧪 Unit Tests

Run unit tests:

make test

🧪 Run Cypress Tests

Run each of these steps in separate terminal sessions:

In the first session, start the frontend in development mode:

make acceptance-frontend-dev-start

In the second session, start the backend acceptance server:

make acceptance-backend-start

In the third session, start the Cypress interactive test runner:

make acceptance-test

📄 License

This project is licensed under the MIT license.

🙏 Credits and Acknowledgements

The development of this add-on was supported by:

Generated using Cookieplone (0.9.9) and cookieplone-templates (62683ae) on 2025-10-14 23:13:02.127574. A special thanks to all contributors and supporters!