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)

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

Self-hosted

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

npm (Webpack / Vite / Rollup)

bash
npm install photopea

js
import Photopea from "photopea";

Core API: The Photopea Class

| Method | Description | |--------|-------------| | Photopea.createEmbed(container) | Creates + injects the iframe, resolves when ready | | new Photopea(window.parent) | Plugin mode: wrap the parent window | | pea.runScript(script) | Run JS string inside Photopea; returns output array | | pea.loadAsset(arrayBuffer) | Load binary file (image, font, brush, etc.) | | pea.openFromURL(url, asSmart) | Open remote URL as new doc or smart object layer | | pea.exportImage(type) | Export current doc; returns Blob ("png" or "jpg") |

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

Step 1 — Embed

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

html
<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:

jsx
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

js
// 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.

js
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

js
// 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:

| String | Format | |--------|--------| | "png" | PNG lossless | | "jpg" | JPEG default | | "jpg:0.8" | JPEG quality 0.0–1.0 | | "webp:0.7" | WebP quality 0.0–1.0 | | "psd" | Full PSD | | "psd:true" | Minified PSD | | "svg:true" | SVG |

Step 5 — Loading Assets

js
// 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

js
// 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:

json
{
  "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

js
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

js
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

html
<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

js
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

js
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

| Property | Type | R/W | Description | |----------|------|-----|-------------| | app.activeDocument | Document | R/W | The currently active document | | app.documents | Documents | R | Collection of all open documents | | app.documents.length | number | R | Count of open documents | | app.documents[i] | Document | R | Access by zero-based index | | app.foregroundColor | SolidColor | R/W | Current foreground color | | app.backgroundColor | SolidColor | R/W | Current background color | | app.preferences.rulerUnits | Units | R/W | Units.PIXELS, Units.CM, Units.INCHES, Units.MM, Units.PICAS, Units.POINTS, Units.PERCENT | | app.preferences.typeUnits | TypeUnits | R/W | TypeUnits.PIXELS, TypeUnits.MM, TypeUnits.POINTS | | app.displayDialogs | DialogModes | R/W | DialogModes.NO, DialogModes.ALL, DialogModes.ERROR |

Methods

| Method | Description | |--------|-------------| | app.open(url) | Open URL as new document | | app.open(url, null, true) | Open URL as smart object layer in active document | | app.echoToOE(string) | Photopea extension — send string to host page (captured by runScript) | | app.showWindow("magiccut") | Photopea extension — open Magic Cut panel | | app.showWindow("vbitmap") | Photopea extension — open Vectorize Bitmap panel | | app.UI.zoomIn() | Zoom in | | app.UI.zoomOut() | Zoom out | | app.UI.fitTheArea() | Fit canvas to viewport | | app.UI.pixelToPixel() | 100% zoom | | app.UI.switchFullscreen() | Toggle fullscreen | | app.UI.scroll(dx, dy) | Scroll by delta | | app.UI.scrollTo(x, y) | Scroll to absolute position |

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

js
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

| Property | Type | R/W | Description | |----------|------|-----|-------------| | width | number | R | Document width in current ruler units | | height | number | R | Document height in current ruler units | | resolution | number | R | DPI (pixels per inch) | | name | string | R/W | Photopea extension — display label (no history step) | | source | string | R/W | Photopea extension — file origin URL or "local,X,NAME" | | mode | DocumentMode | R | DocumentMode.RGB, GRAYSCALE, CMYK, LAB, BITMAP, INDEXEDCOLOR, MULTICHANNEL | | bitsPerChannel | BitsPerChannelType | R | BitsPerChannelType.EIGHT, SIXTEEN, THIRTYTWO | | colorProfileName | string | R | Name of embedded color profile | | activeLayer | Layer/ArtLayer/LayerSet | R/W | Set to activate a layer | | currentLayer | ArtLayer | R/W | Alias for activeLayer | | layers | Layers | R | All top-level layers (both art + group) | | artLayers | ArtLayers | R | All top-level art layers only | | layerSets | LayerSets | R | All top-level group layers only | | selection | Selection | R | The current selection | | channels | Channels | R | All channels | | historyStates | HistoryStates | R | Undo history | | activeHistoryState | HistoryState | R/W | Current history position | | layerComps | LayerComps | R | Layer comps collection | | guides | Guides | R | Guides collection | | pathItems | PathItems | R | Vector paths | | id | number | R | Unique document ID | | saved | boolean | R | Whether document has unsaved changes | | quickMaskMode | boolean | R | Whether in Quick Mask mode | | backgroundLayer | ArtLayer | R | The background layer | | pixelAspectRatio | number | R | Custom pixel aspect ratio (0.1–10.0) | | histogram | array | R | 256-element histogram array |

Methods

| Method | Signature | Description | |--------|-----------|-------------| | resizeImage | (w, h, res, resampleMethod) | Resize image pixels. ResampleMethod: BICUBIC, BILINEAR, NEARESTNEIGHBOR, NONE, BICUBICSHARPER, BICUBICSMOOTHER | | resizeCanvas | (w, h, anchor) | Resize canvas without scaling. AnchorPosition: TOPLEFT, TOPCENTER, TOPRIGHT, MIDDLELEFT, MIDDLECENTER, MIDDLERIGHT, BOTTOMLEFT, BOTTOMCENTER, BOTTOMRIGHT | | rotateCanvas | (degrees) | Rotate entire canvas. Positive = clockwise | | flipCanvas | (direction) | Direction.HORIZONTAL or Direction.VERTICAL | | crop | ([x1,y1,x2,y2], angle, w, h) | Crop canvas. Angle and dimensions are optional | | trim | (trimType, top, left, bottom, right) | Trim transparent/background-color borders. TrimType: TRANSPARENT, TOPLEFT, BOTTOMRIGHT | | revealAll | () | Expand canvas to show clipped content | | flatten | () | Merge all layers into one | | mergeVisibleLayers | () | Merge all visible layers | | rasterizeAllLayers | () | Rasterize all vector/text layers | | changeMode | (mode, options) | Convert color mode (e.g., ChangeMode.GRAYSCALE) | | convertProfile | (profileName, renderingIntent, blackPointCompensation, dither) | Convert color profile | | duplicate | (name, mergedLayers) | Duplicate the document | | close | (saveOptions) | Close document. SaveOptions: DONOTSAVECHANGES, SAVECHANGES, PROMPTTOSAVECHANGES | | save | () | Save (requires server config in embed) | | saveToOE | (format) | Photopea extension — send binary to host. Formats: "png", "jpg:0.8", "webp:0.7", "psd:true", "svg:true" | | clearHistory | () | Photopea extension — clear undo history to free RAM | | exportDocument | (file, exportType, options) | Export to filesystem (triggers ZIP). ExportType: SAVEFORWEB | | paste | (intoSelection) | Paste clipboard into document | | suspendHistory | (historyName, callback) | Wrap multiple ops in one history state |

Practical examples:

js
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.

js
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

| Property | Type | R/W | Description | |----------|------|-----|-------------| | name | string | R/W | Layer name | | visible | boolean | R/W | Layer visibility | | opacity | number | R/W | Layer opacity 0–100 | | fillOpacity | number | R | Fill opacity 0–100 | | blendMode | BlendMode | R/W | Blend mode (see enum below) | | kind | LayerKind | R/W | Layer type (can set to LayerKind.TEXT on empty layer) | | textItem | TextItem | R | Text object (only when kind === LayerKind.TEXT) | | bounds | array | R | [left, top, right, bottom] in current ruler units | | parent | Document/LayerSet | R | Containing object | | typename | string | R | Always "ArtLayer" | | selected | boolean | R | Photopea extension — is layer highlighted in panel | | isBackgroundLayer | boolean | R | Is this the locked background layer | | grouped | boolean | R | Is clipping mask applied | | pixelsLocked | boolean | R | Pixels locked | | positionLocked | boolean | R | Position locked | | transparentPixelsLocked | boolean | R | Transparent pixels locked | | layerMaskDensity | number | R | Layer mask density 0–100 | | layerMaskFeather | number | R | Layer mask feather 0–250 | | vectorMaskDensity | number | R | Vector mask density 0–100 | | vectorMaskFeather | number | R | Vector mask feather 0–250 |

Transform Methods

| Method | Signature | Description | |--------|-----------|-------------| | translate | (deltaX, deltaY) | Move layer by offset | | rotate | (angle, anchor) | Rotate by degrees. AnchorPosition optional (default center) | | resize | (widthPct, heightPct, anchor) | Scale as percentage of current size | | rasterize | (target) | Rasterize. RasterizeType: ENTIRE, FILLCONTENT, LAYERCLIPPINGMASK, LINKEDLAYERS, SHAPE, TEXTCONTENTS, VECTORMASK |

Layer Management Methods

| Method | Signature | Description | |--------|-----------|-------------| | duplicate | () | Duplicate to same document, returns new layer | | duplicate | (doc, placement) | Duplicate to another document | | remove | () | Delete the layer | | merge | () | Merge down; returns the merged ArtLayer | | move | (relativeLayer, placement) | Reorder. ElementPlacement: PLACEBEFORE, PLACEAFTER, PLACEATBEGINNING, PLACEATEND, INSIDE | | copy | (merged) | Copy to clipboard | | cut | () | Cut to clipboard | | clear | () | Cut without clipboard |

Adjustment Methods on ArtLayer

| Method | Signature | Description | |--------|-----------|-------------| | adjustBrightnessContrast | (brightness, contrast) | Brightness -100–100, Contrast -100–100 | | adjustColorBalance | (shadows, midtones, highlights, preserveLuminosity) | Each is [cyan-red, magenta-green, yellow-blue] array | | adjustCurves | (curveShape) | Array of [input,output] pairs per channel | | adjustLevels | (inputRangeStart, inputRangeEnd, gamma, outputRangeStart, outputRangeEnd) | Levels adjustment | | autoLevels | () | Auto levels | | autoContrast | () | Auto contrast | | desaturate | () | Convert to grayscale values in current mode | | equalize | () | Equalize brightness distribution | | invert | () | Invert pixel colors | | posterize | (levels) | Posterize (2–255 levels) | | threshold | (level) | B&W threshold (1–255) | | shadowHighlight | (shadowAmount, shadowWidth, shadowRadius, highlightAmount, highlightWidth, highlightRadius, colorCorrection, midtoneContrast, blackClip, whiteClip) | Shadows/Highlights | | photoFilter | (fillColor, density, luminosity) | Photo filter | | mixChannels | (outputChannels, monochrome) | Channel mixer | | selectiveColor | (colors, cyan, magenta, yellow, black, method) | Selective color |

Filter Methods on ArtLayer

| Method | Signature | Description | |--------|-----------|-------------| | applyGaussianBlur | (radius) | Gaussian blur (0.1–250 px radius) | | applyMotionBlur | (angle, distance) | Motion blur | | applyRadialBlur | (amount, blurMethod, blurQuality) | Radial blur | | applySmartBlur | (radius, threshold, blurQuality, blurMode) | Smart blur | | applyBlur | () | Simple blur | | applyBlurMore | () | Blur more | | applyUnSharpMask | (amount, radius, threshold) | Unsharp mask | | applySharpen | () | Sharpen | | applySharpenEdges | () | Sharpen edges | | applySharpenMore | () | Sharpen more | | applyAddNoise | (amount, distribution, monochromatic) | Add noise. NoiseDistribution: GAUSSIAN, UNIFORM | | applyDespeckle | () | Despeckle | | applyDustAndScratches | (radius, threshold) | Dust and scratches | | applyMedianNoise | (radius) | Median noise reduction | | applyMaximum | (radius) | Maximum filter (dilate) | | applyMinimum | (radius) | Minimum filter (erode) | | applyHighPass | (radius) | High pass | | applyOffset | (horizontal, vertical, undefinedAreas) | Offset. UndefinedAreas: SETTOBACKGROUND, WRAPAROUND, REPEATEDGEPIXELS | | applyRipple | (amount, size) | Ripple. RippleSize: SMALL, MEDIUM, LARGE | | applyWave | (generators, minWavelength, maxWavelength, minAmplitude, maxAmplitude, horizScale, vertScale, waveType, undefinedAreas, randomSeed) | Wave filter | | applyZigZag | (amount, ridges, style) | Zig-Zag | | applyTwirl | (angle) | Twirl | | applyPolarCoordinates | (conversion) | Polar coordinates | | applySpherize | (amount, mode) | Spherize | | applyPinch | (amount) | Pinch (-100–100) | | applyShear | (curve, undefinedAreas) | Shear | | applyDisplace | (horizontalScale, verticalScale, displacementType, undefinedAreas, displacementMapFile) | Displace | | applyClouds | () | Render Clouds | | applyDifferenceClouds | () | Difference Clouds | | applyLensFlare | (brightness, flareCenter, lensType) | Lens Flare. LensType: ZOOMWIDE, ZOOMNORMAL, MOVIE | | applyDiffuseGlow | (graininess, glowAmount, clearAmount) | Diffuse Glow | | applyGlassEffect | (distortion, smoothness, scaling, invert, texture, textureFile) | Glass | | applyOceanRipple | (size, magnitude) | Ocean Ripple | | applyLensBlur | (source, focalDistance, invertDepthMap, shape, radius, bladeCurvature, rotation, brightness, threshold, amount, distribution, monochromatic) | Lens Blur | | applyAverage | () | Average blur | | applyDeInterlace | (eliminateFields, createFields) | De-interlace | | applyNTSC | () | NTSC colors | | applyCustomFilter | (characteristics, scale, offset) | Custom filter (5×5 matrix) | | applyTextureFill | (textureFile) | Texture fill | | applyStyle | (styleName) | Apply a layer style preset by name | | photoFilter | (fillColor, density, luminosity) | Photo Filter |

Practical examples:

js
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

| Property | Type | R/W | Description | |----------|------|-----|-------------| | name | string | R/W | Group name | | visible | boolean | R/W | Group visibility | | opacity | number | R/W | Group opacity 0–100 | | blendMode | BlendMode | R/W | Group blend mode | | bounds | array | R | Bounding box [left,top,right,bottom] | | layers | Layers | R | All layers inside this group | | artLayers | ArtLayers | R | Art layers inside this group | | layerSets | LayerSets | R | Sub-groups inside this group | | parent | Document/LayerSet | R | Parent container | | typename | string | R | Always "LayerSet" |

Methods

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

js
// 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)

| Property | Type | R/W | Description | |----------|------|-----|-------------| | contents | string | R/W | The actual text content | | font | string | R/W | Font PostScript name (e.g. "ArialMT", "Verdana-Bold") | | size | number | R/W | Font size in points | | color | SolidColor | R/W | Text color | | position | array | R/W | [x, y] origin of text (point text) or bounding box top-left | | justification | Justification | R/W | Justification.LEFT, CENTER, RIGHT, FULLJUSTIFY | | kind | TextType | R/W | TextType.POINTTEXT or TextType.PARAGRAPHTEXT | | width | number | R/W | Width of bounding box (paragraph text only) | | height | number | R/W | Height of bounding box (paragraph text only) | | direction | Direction | R/W | Direction.HORIZONTAL or Direction.VERTICAL |

Typography Properties

| Property | Type | R/W | Description | |----------|------|-----|-------------| | leading | number | R/W | Line spacing in points | | tracking | number | R/W | Letter spacing -1000–10000 (1000 = 1 em) | | horizontalScale | number | R/W | Horizontal scaling 0–1000% | | verticalScale | number | R/W | Vertical scaling 0–1000% | | baselineShift | number | R/W | Baseline offset in points | | capitalization | Case | R/W | Case.NORMAL, ALLCAPS, SMALLCAPS | | fauxBold | boolean | R/W | Simulated bold | | fauxItalic | boolean | R/W | Simulated italic | | underline | UnderlineType | R/W | UnderlineType.NONE, UNDERLINELEFT, UNDERLINERIGHT | | strikeThru | StrikeThruType | R/W | StrikeThruType.NONE, STRIKEBOX, STRIKEHEIGHT | | antiAliasMethod | AntiAlias | R/W | AntiAlias.NONE, SHARP, CRISP, STRONG, SMOOTH | | autoKerning | AutoKernType | R/W | AutoKernType.MANUAL, METRICS, OPTICAL | | language | Language | R/W | Language.ENGLISH, etc. | | ligatures | boolean | R/W | Enable ligatures | | alternateLigatures | boolean | R/W | Enable alternate ligatures | | oldStyle | boolean | R/W | Old-style numerals | | noBreak | boolean | R/W | Prevent line breaks in this text | | useAutoLeading | boolean | R/W | Use font's built-in leading | | autoLeadingAmount | number | R/W | Auto leading percentage 0.01–5000 | | hyphenation | boolean | R/W | Enable hyphenation |

Paragraph Properties

| Property | Type | R/W | Description | |----------|------|-----|-------------| | leftIndent | number | R/W | Left indent -1296–1296 | | rightIndent | number | R/W | Right indent -1296–1296 | | firstLineIndent | number | R/W | First line indent -1296–1296 | | spaceBefore | number | R/W | Space before paragraph -1296–1296 | | spaceAfter | number | R/W | Space after paragraph -1296–1296 | | hangingPuntuation | boolean | R/W | Roman hanging punctuation | | textComposer | TextComposer | R/W | TextComposer.ADOBEEVERYLINE, ADOBESINGLELINE |

Warp Properties

| Property | Type | R/W | Description | |----------|------|-----|-------------| | warpStyle | WarpStyle | R/W | WarpStyle.NONE, ARC, ARCH, BULGE, SHELLLOWER, SHELLUPPER, FLAG, WAVE, FISH, RISE, FISHEYE, INFLATE, SQUEEZE, TWIST | | warpDirection | Direction | R/W | Direction.HORIZONTAL or Direction.VERTICAL | | warpBend | number | R/W | Warp bend -100–100 | | warpHorizontalDistortion | number | R/W | Horizontal distortion -100–100 | | warpVerticalDistortion | number | R/W | Vertical distortion -100–100 |

Photopea Extensions

| Property | Type | Description | |----------|------|-------------| | totalTextStyle | string | JSON string with ALL style parameters of the text | | transform | string | JSON array — the affine transform matrix of the text |

Methods

| Method | Description | |--------|-------------| | convertToShape() | Convert text to a filled shape layer with text as clipping path | | createPath() | Create work path from text outlines |

Practical examples:

js
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

js
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

js
// 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

| Property | Type | Description | |----------|------|-------------| | bounds | array | [left, top, right, bottom] bounding rectangle | | solid | boolean | Whether selection is a solid rectangle |

Methods

| Method | Signature | Description | |--------|-----------|-------------| | selectAll | () | Select entire document | | deselect | () | Remove selection | | invert | () | Invert the selection | | select | (region, type, feather, antiAlias) | Select polygon region. Region is array of [x,y] points. SelectionType: REPLACE, ADD, SUBTRACT, INTERSECT | | feather | (radius) | Feather the selection edges | | contract | (radius) | Contract (shrink) selection | | expand | (radius) | Expand selection | | grow | (tolerance, antiAlias) | Grow selection to similar adjacent pixels | | similar | (tolerance, antiAlias) | Select similar pixels throughout document | | smooth | (radius) | Smooth selection edges | | selectBorder | (width) | Select only the border of the current selection | | resize | (widthPct, heightPct, anchor) | Resize selection boundary | | rotate | (angle, anchor) | Rotate selection boundary | | translate | (deltaX, deltaY) | Move selection boundary | | fill | (fillWith, mode, opacity, preserveTransparency) | Fill selection with color or content. fillWith is SolidColor or string | | stroke | (strokeColor, width, location, mode, opacity, preserveTransparency) | Stroke selection border. StrokeLocation: INSIDE, OUTSIDE, CENTER | | copy | (merged) | Copy selection to clipboard | | cut | () | Cut selection to clipboard | | clear | () | Delete selection content | | load | (from, type, invert) | Load selection from channel | | store | (into, type) | Save selection as channel | | makeWorkPath | (tolerance) | Convert to work path |

Practical examples:

js
var sel = doc.selection;

// Rectangle select (top-left to bottom-right)
sel.select([[0,0],[500,0],[500,300],[0,300]]);

// Select all
sel.selectAll();

// Add to existing selection
sel.select([[600,0],[900,0],[900,300],[600,300]], SelectionType.ADD);

// Feather 10px
sel.feather(10);

// Contract by 5px
sel.contract(5);

// Fill with red
var red = new SolidColor();
red.rgb.red = 255; red.rgb.green = 0; red.rgb.blue = 0;
sel.fill(red);

// Stroke selection with black, 3px, inside
var black = new SolidColor();
black.rgb.hexValue = "000000";
sel.stroke(black, 3, StrokeLocation.INSIDE);

// Copy, paste as new layer
sel.copy();
doc.paste();

// Invert and delete (remove background)
sel.invert();
sel.clear();
sel.deselect();

BlendMode Enum — All Values

Used in layer.blendMode (string form in Photopea) and BlendMode constant (standard):

| BlendMode Constant | Photopea String | Name | |----------------------|-----------------|------| | BlendMode.NORMAL | "norm" | Normal | | BlendMode.DISSOLVE | "diss" | Dissolve | | BlendMode.DARKEN | "dark" | Darken | | BlendMode.MULTIPLY | "mul " | Multiply | | BlendMode.COLORBURN | "idiv" | Color Burn | | BlendMode.LINEARBURN | "lbrn" | Linear Burn | | BlendMode.DARKERCOLOR | "dkCl" | Darker Color | | BlendMode.LIGHTEN | "lite" | Lighten | | BlendMode.SCREEN | "scrn" | Screen | | BlendMode.COLORDODGE | "div " | Color Dodge | | BlendMode.LINEARDODGE | "lddg" | Linear Dodge (Add) | | BlendMode.LIGHTERCOLOR | "lgCl" | Lighter Color | | BlendMode.OVERLAY | "over" | Overlay | | BlendMode.SOFTLIGHT | "sLit" | Soft Light | | BlendMode.HARDLIGHT | "hLit" | Hard Light | | BlendMode.VIVIDLIGHT | "vLit" | Vivid Light | | BlendMode.LINEARLIGHT | "lLit" | Linear Light | | BlendMode.PINLIGHT | "pLit" | Pin Light | | BlendMode.HARDMIX | "hMix" | Hard Mix | | BlendMode.DIFFERENCE | "diff" | Difference | | BlendMode.EXCLUSION | "smud" | Exclusion | | BlendMode.SUBTRACT | "fsub" | Subtract | | BlendMode.DIVIDE | "fdiv" | Divide | | BlendMode.HUE | "hue " | Hue | | BlendMode.SATURATION | "sat " | Saturation | | BlendMode.COLOR | "colr" | Color | | BlendMode.LUMINOSITY | "lum " | Luminosity | | BlendMode.PASSTHROUGH | "pass" | Pass Through (groups only) |

js
// Use either form:
layer.blendMode = BlendMode.SCREEN;     // constant
layer.blendMode = "scrn";               // string (Photopea internal form)

LayerKind Enum

| Constant | Description | |----------|-------------| | LayerKind.NORMAL | Regular pixel layer | | LayerKind.TEXT | Text layer | | LayerKind.SMARTOBJECT | Smart Object / linked layer | | LayerKind.SOLIDFILL | Solid color fill layer | | LayerKind.GRADIENTFILL | Gradient fill layer | | LayerKind.PATTERNFILL | Pattern fill layer | | LayerKind.BRIGHTNESSCONTRAST | Brightness/Contrast adjustment layer | | LayerKind.CURVES | Curves adjustment layer | | LayerKind.LEVELS | Levels adjustment layer | | LayerKind.HUESATURATION | Hue/Saturation adjustment layer | | LayerKind.COLORBALANCE | Color Balance adjustment layer | | LayerKind.CHANNELMIXER | Channel Mixer adjustment layer | | LayerKind.GRADIENTMAP | Gradient Map adjustment layer | | LayerKind.INVERSION | Invert adjustment layer | | LayerKind.POSTERIZE | Posterize adjustment layer | | LayerKind.THRESHOLD | Threshold adjustment layer | | LayerKind.SELECTIVECOLOR | Selective Color adjustment layer | | LayerKind.PHOTOFILTER | Photo Filter adjustment layer | | LayerKind.EXPOSURE | Exposure adjustment layer | | LayerKind.VIBRANCE | Vibrance adjustment layer | | LayerKind.COLORLOOKUP | Color Lookup adjustment layer | | LayerKind.LAYER3D | 3D layer (not generally useful in Photopea) | | LayerKind.VIDEO | Video layer |

js
// Identify layer type
var layer = doc.activeLayer;
if (layer.kind === LayerKind.TEXT)         /* text layer */;
if (layer.kind === LayerKind.SMARTOBJECT)  /* smart object */;
if (layer.typename === "LayerSet")         /* group */;

// Filter: collect all text layers recursively
var textLayers = [];
function collectText(parent) {
  for (var i = 0; i < parent.layers.length; i++) {
    var l = parent.layers[i];
    if (l.typename === "LayerSet") collectText(l);
    else if (l.kind === LayerKind.TEXT) textLayers.push(l);
  }
}
collectText(doc);

AnchorPosition Enum

| Constant | Position | |----------|----------| | AnchorPosition.TOPLEFT | Top left | | AnchorPosition.TOPCENTER | Top center | | AnchorPosition.TOPRIGHT | Top right | | AnchorPosition.MIDDLELEFT | Middle left | | AnchorPosition.MIDDLECENTER | Center | | AnchorPosition.MIDDLERIGHT | Middle right | | AnchorPosition.BOTTOMLEFT | Bottom left | | AnchorPosition.BOTTOMCENTER | Bottom center | | AnchorPosition.BOTTOMRIGHT | Bottom right |

ElementPlacement Enum

Used with layer.move(relativeObject, placement):

| Constant | Effect | |----------|--------| | ElementPlacement.PLACEBEFORE | Above the target layer in the panel | | ElementPlacement.PLACEAFTER | Below the target layer in the panel | | ElementPlacement.PLACEATBEGINNING | Top of the layer stack | | ElementPlacement.PLACEATEND | Bottom of the layer stack | | ElementPlacement.INSIDE | Into a LayerSet (makes layer a child) |

ResampleMethod Enum

Used with doc.resizeImage():

| Constant | Description | |----------|-------------| | ResampleMethod.BICUBIC | High quality, good for smooth gradients | | ResampleMethod.BICUBICSHARPER | Best for reduction | | ResampleMethod.BICUBICSMOOTHER | Best for enlargement | | ResampleMethod.BILINEAR | Medium quality | | ResampleMethod.NEARESTNEIGHBOR | No anti-aliasing, fastest | | ResampleMethod.NONE | No resampling (change resolution only) |

SaveOptions Enum

Used with doc.close(saveOption):

| Constant | Meaning | |----------|---------| | SaveOptions.DONOTSAVECHANGES | Discard all changes and close | | SaveOptions.SAVECHANGES | Save then close | | SaveOptions.PROMPTTOSAVECHANGES | Show dialog (may block in headless) |

ExportOptionsSaveForWeb — Export to Filesystem

Used with doc.exportDocument() to write files that Photopea packages into a ZIP.

js
// Export PNG
var pngOpts = new ExportOptionsSaveForWeb();
pngOpts.format      = SaveDocumentType.PNG;
pngOpts.PNG8        = false;    // PNG-24
pngOpts.quality     = 100;
pngOpts.transparency = true;
doc.exportDocument(new File("/export.png"), ExportType.SAVEFORWEB, pngOpts);

// Export JPEG
var jpgOpts = new ExportOptionsSaveForWeb();
jpgOpts.format  = SaveDocumentType.JPEG;
jpgOpts.quality = 80;    // 0–100
doc.exportDocument(new File("/export.jpg"), ExportType.SAVEFORWEB, jpgOpts);

// Export GIF
var gifOpts = new ExportOptionsSaveForWeb();
gifOpts.format     = SaveDocumentType.GIF;
gifOpts.colors     = 256;
gifOpts.dither     = 100;
gifOpts.transparency = true;
doc.exportDocument(new File("/export.gif"), ExportType.SAVEFORWEB, gifOpts);

executeAction — Advanced Operations

Used for operations not exposed in the standard DOM (adjustments applied as adjustment layers, Smart Object editing, etc.). Takes the Photoshop Action Manager approach.

js
// Open Smart Object for editing
var l = doc.layers.getByName("SmartObj");
doc.activeLayer = l;
executeAction(stringIDToTypeID("placedLayerEditContents"));
// Smart Object is now the active document
doc.activeLayer.rotate(90);
doc.save();
doc.close();

// Apply Hue/Saturation as destructive adjustment
var desc = new ActionDescriptor();
var list = new ActionList();
var channel = new ActionDescriptor();
channel.putEnumerated(stringIDToTypeID("presetKind"), stringIDToTypeID("presetKindType"), stringIDToTypeID("presetKindDefault"));
channel.putInteger(stringIDToTypeID("hue"),        20);   // hue shift
channel.putInteger(stringIDToTypeID("saturation"), 30);   // saturation
channel.putInteger(stringIDToTypeID("lightness"),  0);
list.putObject(stringIDToTypeID("hueSaturationAdjustmentV2Layer"), channel);
desc.putList(stringIDToTypeID("adjustment"), list);
executeAction(stringIDToTypeID("hueSaturation"), desc, DialogModes.NO);

// Select a layer by name using AM
function selectLayerByName(name) {
  var desc = new ActionDescriptor();
  var ref  = new ActionReference();
  ref.putName(charIDToTypeID("Lyr "), name);
  desc.putReference(charIDToTypeID("null"), ref);
  desc.putBoolean(charIDToTypeID("MkVs"), false);
  executeAction(charIDToTypeID("slct"), desc, DialogModes.NO);
}

Complete Practical Script Examples

1. Rename all text layers based on their contents

js
app.preferences.rulerUnits = Units.PIXELS;
var doc = app.activeDocument;

function processLayers(parent) {
  for (var i = 0; i < parent.layers.length; i++) {
    var l = parent.layers[i];
    if (l.typename === "LayerSet") processLayers(l);
    else if (l.kind === LayerKind.TEXT) {
      l.name = l.textItem.contents.substring(0, 30);
    }
  }
}
processLayers(doc);
app.echoToOE("done");

2. Export each layer as a separate PNG

js
app.preferences.rulerUnits = Units.PIXELS;
var doc = app.activeDocument;

for (var i = 0; i < doc.layers.length; i++) {
  // Hide all layers
  for (var j = 0; j < doc.layers.length; j++) doc.layers[j].visible = false;
  // Show only this layer
  doc.layers[i].visible = true;
  // Export
  var opts = new ExportOptionsSaveForWeb();
  opts.format  = SaveDocumentType.PNG;
  opts.PNG8    = false;
  opts.quality = 100;
  doc.exportDocument(
    new File("/" + doc.layers[i].name + ".png"),
    ExportType.SAVEFORWEB, opts
  );
}

// Restore visibility
for (var i = 0; i < doc.layers.length; i++) doc.layers[i].visible = true;

3. Find and replace text across all text layers

js
var searchText   = "2024";
var replaceText  = "2025";

function findReplaceText(parent) {
  for (var i = 0; i < parent.layers.length; i++) {
    var l = parent.layers[i];
    if (l.typename === "LayerSet") findReplaceText(l);
    else if (l.kind === LayerKind.TEXT) {
      var t = l.textItem;
      if (t.contents.indexOf(searchText) !== -1) {
        t.contents = t.contents.split(searchText).join(replaceText);
      }
    }
  }
}
findReplaceText(app.activeDocument);
app.echoToOE("Find & Replace complete");

4. Grid of duplicate layers

js
app.preferences.rulerUnits = Units.PIXELS;
var doc   = app.activeDocument;
var layer = doc.activeLayer;
var cols  = 4, rows = 3;
var padX  = 20, padY = 20;
var w = layer.bounds[2] - layer.bounds[0];
var h = layer.bounds[3] - layer.bounds[1];

for (var r = 0; r < rows; r++) {
  for (var c = 0; c < cols; c++) {
    if (r === 0 && c === 0) continue; // skip original
    var copy = layer.duplicate();
    var targetX = layer.bounds[0] + c * (w + padX);
    var targetY = layer.bounds[1] + r * (h + padY);
    copy.translate(targetX - copy.bounds[0], targetY - copy.bounds[1]);
    copy.opacity = 100 - (r * cols + c) * 5;
  }
}

5. Apply watermark from URL

js
app.preferences.rulerUnits = Units.PIXELS;
var doc = app.activeDocument;

// Open watermark as smart object layer
app.open("https://example.com/watermark.png", null, true);
var wm = doc.activeLayer;

// Resize to 20% of document width
var wmW = wm.bounds[2] - wm.bounds[0];
var targetW = doc.width * 0.2;
var scalePct = (targetW / wmW) * 100;
wm.resize(scalePct, scalePct, AnchorPosition.TOPLEFT);

// Move to bottom-right with 20px margin
var wmNewW = wm.bounds[2] - wm.bounds[0];
var wmNewH = wm.bounds[3] - wm.bounds[1];
wm.translate(
  doc.width  - wmNewW - 20 - wm.bounds[0],
  doc.height - wmNewH - 20 - wm.bounds[1]
);
wm.opacity = 60;
app.echoToOE("watermark applied");

6. Get all layer info as JSON

js
function getLayerInfo(parent, depth) {
  depth = depth || 0;
  var result = [];
  for (var i = 0; i < parent.layers.length; i++) {
    var l = parent.layers[i];
    var info = {
      name:    l.name,
      type:    l.typename,
      visible: l.visible,
      opacity: l.opacity,
      depth:   depth
    };
    if (l.typename === "ArtLayer") {
      info.kind   = l.kind.toString();
      info.bounds = [l.bounds[0], l.bounds[1], l.bounds[2], l.bounds[3]];
      if (l.kind === LayerKind.TEXT) {
        info.text = l.textItem.contents;
        info.font = l.textItem.font;
        info.size = l.textItem.size;
      }
    } else if (l.typename === "LayerSet") {
      info.children = getLayerInfo(l, depth + 1);
    }
    result.push(info);
  }
  return result;
}
app.echoToOE(JSON.stringify(getLayerInfo(app.activeDocument)));

Common Mistakes & Gotchas

| Problem | Cause | Fix | |---------|-------|-----| | createEmbed never resolves | Container has no size | Add width + height CSS to the container <div> | | runScript returns ["done"] with no data | No echoToOE in script | Add app.echoToOE(value) for anything you want back | | result[0] is "done", not the expected value | echoToOE not reached | Check script logic for early exit or errors | | Images won't load (network error) | CORS | Server must respond with Access-Control-Allow-Origin: * | | openFromURL(url, true) layer not ready | Async loading lag | Use addImageAndWait utility | | exportImage only PNG/JPG | exportImage limitation | Use runScript("saveToOE('webp:0.85')") for other formats | | Pixel coordinates behave unexpectedly | Wrong ruler units | Always set app.preferences.rulerUnits = Units.PIXELS first | | Text size set but looks different | Wrong type units | Set app.preferences.typeUnits = TypeUnits.PIXELS | | Layer not found by name | Wrong layer level | Layers are scoped; use recursive search for nested layers | | layer.bounds[0] returns a UnitValue, not number | Ruler units issue | Force Units.PIXELS before reading bounds | | Smart Object edit hangs | Missing doc.save(); doc.close() | Always save + close when done editing SO | | React double-mount in dev | Strict Mode | Use if (peaRef.current) return guard in useEffect |

Limitations

• This skill covers host-page integration patterns; it does not replace Photopea's own terms, API documentation, or licensing guidance.
• Remote URL loading depends on browser CORS behavior, network availability, and the user's Photopea account/session state.
• runScript executes scripts inside the embedded Photopea document context. Only run scripts you understand and only with user-approved files.
• Serialize dynamic values with JSON.stringify before embedding them in a runScript string. Never concatenate user-provided URLs, layer names, or text directly into Photopea script source.
• Export behavior can vary by document size, browser memory limits, and the formats supported by the active Photopea runtime.

Sources

• photopea.js: https://github.com/yikuansun/PhotopeaAPI
• npm: https://www.npmjs.com/package/photopea
• Photopea Live Messaging API: https://www.photopea.com/api/live
• Photopea Script reference: https://www.photopea.com/learn/scripts
• Photoshop JS Scripting reference (compatible): https://theiviaxx.github.io/photoshop-docs/Photoshop/index.html
• Plugin dev gists (addImageAndWait, getDocumentAsImage): https://gist.github.com/yikuansun/c0f1a602b4e9d4e344a41c4f49ded3bf