Imported from yashas-30/NYX (.agents/skills/photopea-embedded-editor/SKILL.md). Install upstream with npx skills add yashas-30/NYX --skill photopea-embedded-editor. Copyright stays with the author (MIT).

Photopea Embedded Editor Skill

Using photopea.js (yikuansun/PhotopeaAPI) in Websites & Apps

When to Use This Skill

Use this skill for every task that involves:

• Embedding Photopea as an image editor inside a webpage or web app
• Controlling an embedded Photopea instance from your JavaScript code
• Automating image editing workflows from a host page (open files, run scripts, export results)
• Building an image editing feature into your product using Photopea as the engine
• Writing scripts to manipulate documents, layers, text, selections, filters, colors, and paths

Do NOT use raw postMessage wiring — always use photopea.js as the wrapper.

Library: photopea.js

photopea.js is a Promises-based JavaScript wrapper around the Photopea Live Messaging API. Repository: https://github.com/yikuansun/PhotopeaAPI npm package: https://www.npmjs.com/package/photopea

Installation

CDN (no build step)

<script src="https://cdn.jsdelivr.net/npm/photopea@1.1.1/dist/photopea.min.js"></script>

Self-hosted

<script src="./photopea.min.js"></script>

npm (Webpack / Vite / Rollup)

npm install photopea

import Photopea from 'photopea';

Core API: The Photopea Class

All methods return Promises — always await or .then().

Step 1 — Embed

The container <div> must have a fixed width and height before calling createEmbed.

<div id="editor" style="width:1000px; height:650px;"></div>
<script src="https://cdn.jsdelivr.net/npm/photopea@1.1.1/dist/photopea.min.js"></script>
<script>
  Photopea.createEmbed(document.getElementById('editor')).then(async (pea) => {
    // pea is ready
  });
</script>

React:

import { useEffect, useRef } from 'react';
import Photopea from 'photopea';

export default function Editor() {
  const containerRef = useRef(null);
  const peaRef = useRef(null);

  useEffect(() => {
    if (!containerRef.current || peaRef.current) return;
    Photopea.createEmbed(containerRef.current).then((pea) => {
      peaRef.current = pea;
    });
  }, []);

  return <div ref={containerRef} style={{ width: '100%', height: '650px' }} />;
}

Step 2 — Opening Files

// Remote URL → new document
await pea.openFromURL('https://example.com/design.psd', false);

// Remote URL → smart object layer inside current document
await pea.openFromURL('https://example.com/overlay.png', true);

// Local file (user input → ArrayBuffer → loadAsset)
document.getElementById('fileInput').addEventListener('change', async (e) => {
  const buf = await e.target.files[0].arrayBuffer();
  await pea.loadAsset(buf);
});

// Base64 data URI via runScript
await pea.runScript(`app.open("data:image/png;base64,iVBORw0...");`);

Step 3 — Running Scripts

runScript sends a JS string, returns an array of app.echoToOE(...) values + "done" last.

const result = await pea.runScript(`app.echoToOE("hello");`);
// result → ["hello", "done"]

// Return structured data
const out = await pea.runScript(`
  app.echoToOE(JSON.stringify({
    width:  app.activeDocument.width,
    height: app.activeDocument.height,
    layers: app.activeDocument.layers.length
  }));
`);
const info = JSON.parse(out[0]);

Step 4 — Exporting

// PNG Blob (via exportImage)
const blob = await pea.exportImage('png');
document.getElementById('preview').src = URL.createObjectURL(blob);

// JPEG Blob
const blob = await pea.exportImage('jpg');

// WebP / PSD / quality-controlled JPEG via saveToOE
const result = await pea.runScript(`app.activeDocument.saveToOE("webp:0.85");`);
const webpBlob = new Blob([result[0]], { type: 'image/webp' });

const result = await pea.runScript(`app.activeDocument.saveToOE("psd:true");`);
const psdBlob = new Blob([result[0]], { type: 'application/octet-stream' });

// Trigger download
async function download(pea, filename = 'export.png') {
  const blob = await pea.exportImage('png');
  const a = Object.assign(document.createElement('a'), {
    href: URL.createObjectURL(blob),
    download: filename,
  });
  a.click();
}

Export format strings for saveToOE:

Step 5 — Loading Assets

// Font
const buf = await (await fetch('https://example.com/MyFont.otf')).arrayBuffer();
await pea.loadAsset(buf);
// Now usable in textItem.font

// Brush
await pea.loadAsset(await (await fetch('Nature.ABR')).arrayBuffer());

// Gradient
await pea.loadAsset(await (await fetch('Gradients.GRD')).arrayBuffer());

Step 6 — Plugin Mode

// Your page is inside Photopea's sidebar iframe
const pea = new Photopea(window.parent);

const out = await pea.runScript(`app.echoToOE(app.activeDocument.width);`);
console.log('Width:', out[0]);

// Load an asset from your plugin
const buf = await (await fetch('https://my-assets.com/sticker.png')).arrayBuffer();
await pea.loadAsset(buf);

Plugin config:

{
  "environment": {
    "plugins": [
      {
        "name": "My Plugin",
        "url": "https://my-plugin.example.com",
        "icon": "===https://my-plugin.example.com/icon.png"
      }
    ]
  }
}

Utility Patterns

addImageAndWait — robust async layer insertion

async function addImageAndWait(pea, imgURI) {
  let count = 'done';
  while (count === 'done')
    count = (await pea.runScript(`app.echoToOE(app.activeDocument.layers.length)`))[0];
  count = parseInt(count);

  const imageUrlLiteral = JSON.stringify(imgURI);
  await pea.runScript(`app.open(${imageUrlLiteral}, null, true);`);

  return new Promise((resolve) => {
    const check = async () => {
      const n = parseInt(
        (await pea.runScript(`app.echoToOE(app.activeDocument.layers.length)`))[0]
      );
      n === count + 1 ? resolve() : setTimeout(check, 50);
    };
    check();
  });
}

getDocumentAsImage — returns <img> element

async function getDocumentAsImage(pea) {
  const result = await pea.runScript(`app.activeDocument.saveToOE('png')`);
  return new Promise((resolve) => {
    const fr = new FileReader();
    fr.addEventListener('load', (e) => {
      const img = new Image();
      img.src = e.target.result;
      resolve(img);
    });
    fr.readAsDataURL(new Blob([result[0]], { type: 'image/png' }));
  });
}

Real-World Patterns

Pattern A — Open + Export UI

<input type="file" id="fileInput" accept="image/*,.psd" />
<button id="exportBtn">Export PNG</button>
<div id="editor" style="width:100%;height:600px;"></div>
<script src="https://cdn.jsdelivr.net/npm/photopea@1.1.1/dist/photopea.min.js"></script>
<script>
  let pea;
  Photopea.createEmbed(document.getElementById('editor')).then((p) => (pea = p));

  document.getElementById('fileInput').addEventListener('change', async (e) => {
    await pea.loadAsset(await e.target.files[0].arrayBuffer());
  });
  document.getElementById('exportBtn').addEventListener('click', async () => {
    const blob = await pea.exportImage('png');
    const a = Object.assign(document.createElement('a'), {
      href: URL.createObjectURL(blob),
      download: 'export.png',
    });
    a.click();
  });
</script>

Pattern B — Template + Text Edit + Export

async function generateCard(pea, name, tagline) {
  await pea.openFromURL('https://example.com/card.psd', false);
  const nameLiteral = JSON.stringify(name);
  const taglineLiteral = JSON.stringify(tagline);
  await pea.runScript(`
    app.activeDocument.layers.getByName("Name").textItem.contents    = ${nameLiteral};
    app.activeDocument.layers.getByName("Tagline").textItem.contents = ${taglineLiteral};
  `);
  return await pea.exportImage('png');
}

Pattern C — Batch Watermark

async function batchWatermark(pea, imageURLs, watermarkURL) {
  const results = [];
  for (const url of imageURLs) {
    await pea.openFromURL(url, false);
    await pea.openFromURL(watermarkURL, true);
    await pea.runScript(`
      var doc = app.activeDocument, wm = doc.activeLayer;
      wm.translate(doc.width - wm.bounds[2] - 20, doc.height - wm.bounds[3] - 20);
      wm.opacity = 70;
    `);
    results.push(await pea.exportImage('png'));
    await pea.runScript(`app.activeDocument.close(SaveOptions.DONOTSAVECHANGES);`);
  }
  return results;
}

FULL SCRIPTING API REFERENCE

All code in this section runs inside pea.runScript("...") strings. Photopea implements the Adobe Photoshop CC 2015 JavaScript scripting interface. Any Photoshop script targeting that version should work in Photopea.

app — Application Object

Properties

Methods

Important: Always set ruler units to pixels at the start of any script that uses pixel measurements:

var savedUnits = app.preferences.rulerUnits;
app.preferences.rulerUnits = Units.PIXELS;
// ... your code ...
app.preferences.rulerUnits = savedUnits;

Document — Document Object

Access via app.activeDocument or app.documents[i].

Properties

Methods

Practical examples:

var doc = app.activeDocument;

// Resize image to 1920×1080 at 72dpi bicubic
doc.resizeImage(1920, 1080, 72, ResampleMethod.BICUBIC);

// Expand canvas to 2000px wide, keeping content centered
doc.resizeCanvas(2000, doc.height, AnchorPosition.MIDDLECENTER);

// Crop to a region
doc.crop([100, 100, 900, 600]);

// Trim transparent edges
doc.trim(TrimType.TRANSPARENT, true, true, true, true);

// Flip horizontal
doc.flipCanvas(Direction.HORIZONTAL);

// Change to grayscale
doc.changeMode(ChangeMode.GRAYSCALE);

// One undo step for many operations
doc.suspendHistory('Batch Edit', 'action');
// (Inside Photopea, all ops become one history state)

// Export PNG to filesystem (triggers ZIP download)
var opts = new ExportOptionsSaveForWeb();
opts.format = SaveDocumentType.PNG;
opts.PNG8 = false;
opts.quality = 100;
doc.exportDocument(new File('/output.png'), ExportType.SAVEFORWEB, opts);

// Close without saving
doc.close(SaveOptions.DONOTSAVECHANGES);

Layers / ArtLayers / LayerSets Collections

These collections exist on Document, LayerSet (groups within groups), and can be iterated.

var doc = app.activeDocument;

// Access
doc.layers; // all top-level (art + groups)
doc.artLayers; // top-level art layers only
doc.layerSets; // top-level group layers only

// By index (0 = topmost)
doc.layers[0];
doc.layers[doc.layers.length - 1]; // bottommost

// By name (throws if not found)
doc.layers.getByName('Background');
doc.artLayers.getByName('Logo');
doc.layerSets.getByName('Header Group');

// Add
var newLayer = doc.artLayers.add(); // new blank art layer
var newGroup = doc.layerSets.add(); // new group
var innerLayer = newGroup.artLayers.add(); // layer inside a group

// Remove
doc.artLayers.getByName('Temp').remove();

// Iterate all layers recursively
function walkLayers(parent) {
  for (var i = 0; i < parent.layers.length; i++) {
    var l = parent.layers[i];
    if (l.typename === 'LayerSet') walkLayers(l);
    else /* ArtLayer */ processLayer(l);
  }
}
walkLayers(doc);

ArtLayer — Individual Layer

Properties

Transform Methods

Layer Management Methods

Adjustment Methods on ArtLayer

Filter Methods on ArtLayer

Practical examples:

var layer = app.activeDocument.activeLayer;

// Move to absolute position (layer.bounds[0] = current left edge)
layer.translate(200 - layer.bounds[0], 100 - layer.bounds[1]);

// Rotate 45° around center
layer.rotate(45);

// Scale to 50% keeping center
layer.resize(50, 50, AnchorPosition.MIDDLECENTER);

// Gaussian blur radius 10
layer.applyGaussianBlur(10);

// Unsharp mask
layer.applyUnSharpMask(50, 2, 0);

// Levels: input 0–200, gamma 1.2, output 0–255
layer.adjustLevels(0, 200, 1.2, 0, 255);

// Brightness +20, Contrast +10
layer.adjustBrightnessContrast(20, 10);

// Invert
layer.invert();

// Rasterize text
layer.rasterize(RasterizeType.TEXTCONTENTS);

// Duplicate layer
var copy = layer.duplicate();
copy.name = 'Layer Copy';

// Move layer below another
var target = doc.layers.getByName('Background');
layer.move(target, ElementPlacement.PLACEAFTER);

LayerSet — Group Layer

A LayerSet is a folder/group in the Layers panel. It has the same layer management methods as Document.

Properties

Methods

Same as Document for layer management: layers.add(), artLayers.add(), layerSets.add(), .getByName(), plus duplicate(), remove(), move().

// Create group with layers inside
var group = doc.layerSets.add();
group.name = 'Product Card';

var bgLayer = group.artLayers.add();
bgLayer.name = 'Background';
var textLayer = group.artLayers.add();
textLayer.kind = LayerKind.TEXT;
textLayer.textItem.contents = 'Buy Now';
textLayer.textItem.size = 36;

// Collapse/expand group (Photopea specific, not in standard DOM)
// Use visibility as workaround

// Get specific layer inside a group
var innerLayer = doc.layerSets.getByName('Header Group').artLayers.getByName('Title');

TextItem — Text Layer Content

Access via layer.textItem on any layer with layer.kind === LayerKind.TEXT.

Core Properties (most commonly used)

Typography Properties

Paragraph Properties

Warp Properties

Photopea Extensions

Methods

Practical examples:

var layer = doc.layers.getByName('Headline');
var text = layer.textItem;

// Set content
text.contents = 'Hello World';

// Style
text.font = 'Verdana-Bold';
text.size = 72;
text.color.rgb.hexValue = 'FF0000'; // red

// Position point text at (50, 100)
text.position = [50, 100];

// Center align
text.justification = Justification.CENTER;

// Paragraph text with bounding box
text.kind = TextType.PARAGRAPHTEXT;
text.width = new UnitValue('400 pixels');
text.height = new UnitValue('200 pixels');

// Letter spacing
text.tracking = 100; // 10% spacing

// Scale text horizontally to 80%
text.horizontalScale = 80;

// Warp arc
text.warpStyle = WarpStyle.ARC;
text.warpBend = 30;

// Read all text styles as JSON (Photopea extension)
var styles = JSON.parse(text.totalTextStyle);
app.echoToOE(JSON.stringify(styles));

Creating a Text Layer from Scratch

app.preferences.rulerUnits = Units.PIXELS;

var layer = doc.artLayers.add();
layer.kind = LayerKind.TEXT; // Convert blank layer to text
layer.name = 'My Title';

var text = layer.textItem;
text.contents = 'Welcome';
text.font = 'ArialMT';
text.size = 48;
text.justification = Justification.CENTER;
text.position = [doc.width / 2, 100];

var color = new SolidColor();
color.rgb.red = 255;
color.rgb.green = 255;
color.rgb.blue = 255;
text.color = color;

SolidColor — Color Object

// RGB (most common in Photopea)
var c = new SolidColor();
c.rgb.red = 255; // 0–255
c.rgb.green = 128;
c.rgb.blue = 0;
c.rgb.hexValue = 'FF8000'; // Set via hex string (no #)

// CMYK
var c2 = new SolidColor();
c2.cmyk.cyan = 0; // 0–100
c2.cmyk.magenta = 50;
c2.cmyk.yellow = 100;
c2.cmyk.black = 0;

// Grayscale
var c3 = new SolidColor();
c3.gray.gray = 50; // 0–100

// HSB
var c4 = new SolidColor();
c4.hsb.hue = 30; // 0–360
c4.hsb.saturation = 100; // 0–100
c4.hsb.brightness = 100; // 0–100

// Lab
var c5 = new SolidColor();
c5.lab.l = 50; // 0–100
c5.lab.a = 20; // -128–127
c5.lab.b = 40; // -128–127

// Set as foreground color
app.foregroundColor = c;

// Use with selection fill
doc.selection.selectAll();
doc.selection.fill(c);
doc.selection.deselect();

Selection — Selection Object

Access via doc.selection.

Properties

Methods

Truncated - read the full file at https://github.com/yashas-30/NYX/blob/dd26e5d48ff01223b24acc58beb71200f2258004/.agents/skills/photopea-embedded-editor/SKILL.md.