First Steps in Photoshop Scripting

Writing Photoshop scripts is often tedious and painful (hello, bugs), but it can also be genuinely useful and fun. If you already know JavaScript, getting started is fairly straightforward.

Setup

You will need Adobe ExtendScript Toolkit, Photoshop, and a bit of patience.

After installation, launch ExtendScript Toolkit and in the top-left dropdown switch from "ExtendScript Toolkit CC" to Photoshop. This makes the script run in Photoshop when you press the green play button.

That is all you need to start. You can write and run all code below directly in ExtendScript Toolkit, then save it as a `.jsx` file for everyday use.

I will skip deep object-model theory here; official Adobe docs cover that in detail. Links are at the end.

Let's begin.

Working with the active layer

Most scripts start with the active layer. The chain is Photoshop app (`app`) -> active document (`activeDocument`) -> active layer (`activeLayer`).

app.activeDocument.activeLayer

A layer has properties and methods, just like other Photoshop objects (documents, channels, text items, vector shapes, etc.).

For example, to get the layer name, use the name property.

// Show a dialog with the active layer name
alert(app.activeDocument.activeLayer.name);

To rename a layer:

app.activeDocument.activeLayer.name = 'My favorite layer';

To hide or show a layer, use visible.

// true - show layer
// false - hide layer
app.activeDocument.activeLayer.visible = false;

To move layer content across the canvas, use translate.

app.activeDocument.activeLayer.translate(X, Y);

You can also read layer bounds (bounds), change opacity (opacity) and fill opacity (fillOpacity), duplicate (duplicate), resize (resize), and more.

The full list of properties/methods is in the official documentation linked below.

Making it more interesting

Suppose we have a document with a text layer.

Let's write a script that reads font family, size, line height, and text color, then inserts those values into the layer name.

// Read color
var textColor = app.activeDocument.activeLayer.textItem.color.rgb.hexValue;

// Font
var textFont = app.activeDocument.activeLayer.textItem.font;

// Font size
var textSize = app.activeDocument.activeLayer.textItem.size;

// Rename layer
app.activeDocument.activeLayer.name = textFont+', '+textSize+', #'+textColor;

After running this script, the layer name becomes something like:

ArialMT, 14 pt, #000000

Or nothing may happen, because Photoshop has quirks.

For example, if a new text layer keeps the default black color (`#000000`), Photoshop may fail to return that value. One common workaround is JavaScript try...catch: run code in try, and if it fails, handle fallback logic in catch.

try {
    // your code
} catch(e) {
    // fallback code when try block fails
}

So, let's fix possible color-resolution errors:

try {
    var textColor = app.activeDocument.activeLayer.textItem.color.rgb.hexValue;
} catch(e) {
    var textColor = '000000';
}

Result:

try {
    var textColor = app.activeDocument.activeLayer.textItem.color.rgb.hexValue;
} catch(e) {
    var textColor = '000000';
}

var textFont = app.activeDocument.activeLayer.textItem.font;
var textSize = app.activeDocument.activeLayer.textItem.size;
    
app.activeDocument.activeLayer.name = textFont+', '+textSize+', #'+textColor;

Now the script behaves reliably.

Let's make it a bit better.

Below is a final version for self-study.

// Store the active layer for cleaner code,
// so we do not repeat a long expression each time
var myLayer = app.activeDocument.activeLayer;

// Ensure this is a text layer
if (myLayer.kind == 'LayerKind.TEXT') {

    // Read text color, handle Photoshop bug, add comma
    try{
        var textColor = ', #'+myLayer.textItem.color.rgb.hexValue;
    } catch(e) {
        var textColor = ', #000000';
    }

    // Read line-height and handle possible auto-value bug
    // when auto is returned we keep this part empty
    try{
        var textLineHeight = '/'+parseInt(myLayer.textItem.leading)+'px';
    } catch(e) {
        var textLineHeight = '';
    }

    // Resolve human-readable system font name
    // instead of PostScript font name
    var textFont = app.fonts.getByName(myLayer.textItem.font).name;
    
    // Take numeric size without pt, append px and comma
    var textSize = ', '+parseInt(myLayer.textItem.size)+'px';
 
    myLayer.name = textFont + textSize + textLineHeight + textColor;
}

In the end, the layer name becomes something like:

Arial Bold Italic 30px/40px #333000

or

PT Sans 18px #ff0000

Useful resources

• Adobe ExtendScript Toolkit CC - where we write scripts
• Adobe Introduction to Scripting (PDF)
• Photoshop CC Scripting Guide (PDF)
• Photoshop Scripting Adobe Community - official community
• ps-script.com - unofficial Photoshop scripting forum