pixedi

A lightweight, embeddable React image editor component.

pixedi provides a ready-to-use image editing UI with cropping, resizing, image adjustments, predefined artistic filters, horizontal/vertical flip, free-angle rotation, undo/redo, and social-media size presets. It is built for React applications.

Features

• Crop with free or fixed-ratio selection
• Shape crop — mask the image with one of 20 shapes, filled or outlined
• Resize by exact pixel dimensions
• Horizontal and vertical flip
• Free-angle rotation with automatic zoom (see Rotate)
• Image filters — two modes (see Filters below)
• Undo/redo history
• Social-media size presets (Facebook, Instagram, LinkedIn)
• Single-tool mode — a minimal editor when only one tool is enabled (see Single-tool mode)
• React component and standalone UMD widget
• TypeScript declarations included

Installation

npm install pixedi
# or
pnpm add pixedi
# or
yarn add pixedi

pixedi requires the following peer dependencies:

npm install react react-dom

React Component

Import

import { Pixedi } from "pixedi";

Usage

import { Pixedi } from "pixedi";

function App() {
  return (
    <div style={{ width: "100vw", height: "100vh" }}>
      <Pixedi
        image="https://example.com/photo.jpg"
        onSave={async (image) => {
          // image is a Blob by default, or a base64 data URI when
          // settings.exportAs is "base64"
          console.log(image);
        }}
        onBack={() => {
          // Handle back/cancel action
          console.log("User cancelled editing");
        }}
      />
    </div>
  );
}

function AppBase64() {
  return (
    <div style={{ width: "100vw", height: "100vh" }}>
      <Pixedi
        image="https://example.com/photo.jpg"
        onSave={async (base64) => {
          // Receives a base64 data URI: data:image/webp;base64,...
          console.log(base64);
        }}
        onBack={() => {
          console.log("User cancelled editing");
        }}
        settings={{
          exportAs: "base64",
        }}
      />
    </div>
  );
}

Props

| Prop | Type | Description | | -------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------- | | image | string \| Blob | URL, base64 data URI, or Blob of the image to edit. | | onSave | (image: Blob \| string) => void \| Promise<void> | Called when the user clicks Save. Receives the edited image as a Blob or a base64 data URI. | | onBack | () => void | Called when the user clicks Back/Cancel. | | theme | "light" \| "dark" | UI color theme. Defaults to "light". | | settings | Settings | Optional editor settings (see below). | | translations | Record<string, string> | Optional UI label overrides (see Localization). |

Settings

| Setting | Type | Default | Description | | -------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | tools | Array<"resize" \| "crop" \| "presetCrop" \| "flip" \| "rotate" \| "filters" \| "shapes"> | ["resize","crop","presetCrop","flip","rotate","filters","shapes"] | Tools to show in the sidebar. A single tool switches to single-tool mode. Use an empty array to disable editing. | | infobar | boolean | true | Show the image info panel below the canvas. | | quality | number | 0.85 | Output compression quality (0–1) for JPEG/WebP. | | saveAsWEBP | boolean | false | Encode the final image as WebP. | | exportAs | "blob" \| "base64" | "blob" | Pass the result to onSave as a Blob or as a base64 data URI (data:<mimeType>;base64,...). | | background | "circled" \| "diagonals" \| "rhombus" | — | Apply a decorative pattern to the editor frame background. | | maxImageSize | number | — | Max length in px of the longest side of the saved image. Larger images are downscaled proportionally on Save. |

Localization

Pass a translations object to override any UI label. Only the keys you provide are replaced — the rest fall back to the English defaults.

<Pixedi
  image="https://example.com/photo.jpg"
  onSave={async (image) => console.log(image)}
  onBack={() => console.log("User cancelled editing")}
  translations={{
    save: "Enregistrer",
    crop: "Recadrer",
    filters: "Filtres",
  }}
/>

Available keys and their default English values:

| Key | Default | | ---------------------- | ---------------------- | | save | Save | | reset | Reset | | resize | Resize | | crop | Crop | | presetCrop | Presets | | flip | Flip | | rotate | Rotate | | filters | Filters | | shapes | Shapes | | width | Width | | height | Height | | freeform | Free form | | origin | Original | | horizontal | Horizontal | | vertical | Vertical | | predefinedFilters | Predefined filters | | compare | Compare | | before | Before | | after | After | | saturate | Saturate | | sepia | Sepia | | invert | Invert | | hueRotate | Hue Rotate | | brightness | Brightness | | contrast | Contrast | | fullfield | Fullfield | | outlined | Outlined | | msgNoTools | No tools selected | | msgFailedToLoadImage | Failed to load image |

Single-tool mode

Passing exactly one entry in settings.tools renders a minimal editor: no header, sidebar or infobar — just the image with that tool already open.

<Pixedi
  image="https://example.com/photo.jpg"
  onSave={async (image) => console.log(image)}
  onBack={() => console.log("User cancelled editing")}
  settings={{ tools: ["crop"] }}
/>

In this mode the tool's own buttons drive the flow:

• Close (red ✕) calls onBack immediately.
• Save (green ✓) applies the change, encodes the image and calls onSave with the result. While saving, the check icon is replaced by a spinner and both buttons are disabled.

After a successful save the editor stays mounted and reopens the tool on the newly produced image, so the user can keep editing or close.

Filters

The Filters tool offers two modes, switchable via the toolbar toggle. Filter state is preserved in undo/redo history and baked into the image on save.

CSS adjustments

Slider-based adjustments applied via CSS filter. Each slider affects only that property; the rest stay at their defaults.

| Filter | Range | Default | | ---------- | ------ | ------- | | Saturate | 0–200% | 100% | | Sepia | 0–100% | 0% | | Invert | 0–100% | 0% | | Hue-Rotate | 0–360° | 0° | | Brightness | 0–200% | 100% | | Contrast | 0–200% | 100% |

Predefined artistic filters

SVG-based filters selected from a dropdown. Each is a non-destructive preset applied as a single named filter.

| Filter | Description | | ---------------- | ----------------------------------------------- | | Vintage | Warm reddish tint with boosted reds | | Olive Army | Desaturated olive-green tone | | Warm Sunset | Boosted reds and oranges, reduced blues | | Sin City Red | High-contrast red channel, grey everything else | | CRT Monitor | Scanline overlay simulating a CRT screen | | Grain / Noise | Film-grain texture via fractal noise | | Cross-Processing | Shifted colour curves for a lo-fi look | | X-Ray | Inverted luminance, blue-green hue | | Vignette Shadow | VIGNETTE SHADOW FRAME |

Compare mode

Click the Compare button in the filter toolbar to toggle a side-by-side before/after view. The original image is shown at full opacity while the comparison is active.

Rotate

The Rotate tool ("rotate") shows an orbital dial over the image. Drag the thumb to any angle, or click one of the presets every 45°; the preview follows live and the current angle is shown in the middle of the dial.

• No empty corners — at angles that are not a multiple of 90° the image is zoomed in just enough to cover the frame, and the overflow is trimmed.
• Orientation — the frame follows the nearest quarter turn: a 1400×1100 image becomes 1100×1400 from 45° up to 135°, and so on.
• Output size — the saved image keeps the oriented size, so free angles upscale the zoomed area slightly.
• Apply / cancel — the green ✓ adds the rotation to the history (or saves directly in single-tool mode); the red ✕ discards it.
• Editable — reopening the tool shows the committed angle, and changing it re-renders from the original image instead of zooming again. Crop, flip, resize and shapes keep working on a rotated image.

Shape crop

The Shapes tool ("shapes") crops the image to a silhouette selected from a dropdown of 20 shapes (star, heart, shield, tag, flower, droplet, moon, circle, ellipse, polygons, and more). A toolbar toggle switches between two modes:

• Fullfield — the image is clipped to the filled shape.
• Outlined — only the shape's outline is kept, with a border-width slider (in % of the image).

Widget CDN

For non-React environments, use the standalone UMD widget from a CDN. See README.widget.md for full usage instructions, API reference, and examples.

Pin to a specific version in production:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/widget/pixedi-widget.js"></script>

For the latest version (use only for testing):

<script src="https://cdn.jsdelivr.net/npm/pixedi/dist/widget/pixedi-widget.js"></script>

TypeScript

TypeScript declarations are included under dist/lib/index.d.ts. No additional @types package is required.

License

MIT