Selection

Represents a selected area or areas in the document. If there is no active selection, the bounds will return null. The selection is pixel-based, though 8-bit transparency is possible.

Pixel selection targets where pixel filters are applied, or from where the histogram measurement is sourced.

Copy
const { app, constants } = require("photoshop");
const doc = app.activeDocument;

await doc.selection.selectRectangle(
    {top: 50, left: 50, bottom: 100, right: 100},
    constants.SelectionType.REPLACE
);
doc.selection.bounds; // {{top: 50, left: 50, bottom: 100, right: 100}
doc.selection.solid;  // true

await doc.selection.selectEllipse(
    {top: 50, left: 70, bottom: 140, right: 100},
    constants.SelectionType.EXTEND
);
doc.selection.bounds; // {top: 50, left: 50, bottom: 140, right: 100}
doc.selection.solid;  // false

Copied to your clipboard
const { app, constants } = require("photoshop");
const doc = app.activeDocument;

await doc.selection.selectRectangle(
    {top: 50, left: 50, bottom: 100, right: 100},
    constants.SelectionType.REPLACE
);
doc.selection.bounds; // {{top: 50, left: 50, bottom: 100, right: 100}
doc.selection.solid;  // true

await doc.selection.selectEllipse(
    {top: 50, left: 70, bottom: 140, right: 100},
    constants.SelectionType.EXTEND
);
doc.selection.bounds; // {top: 50, left: 50, bottom: 140, right: 100}
doc.selection.solid;  // false

Pixel selection while in Quick Mask Mode: When a user switches into Quick Mask Mode, the selection is temporarily shown as a channel instead of the "marching ants" border. While in Quick Mask Mode, new pixel selections can be made via Scripting. However, upon exiting Quick Mask Mode, the Quick Mask Channel will become the active selection.

Properties

Methods

contract

async : Promise<void>

Contract (shrink) the selection by the specified amount.

If the contraction amount is greater than the selected area radius, the selected area will disappear entirely. If there are no other active selected areas, then there will be no active selection altogether.

Copy
await doc.selection.contract(8);
Copied to your clipboard
await doc.selection.contract(8);

UI Location: Select > Modify > Contract

Parameters

deselect

async : Promise<void>

Cancel the current selection. The bounds value will then be null.

Copy
await doc.selection.deselect();
Copied to your clipboard
await doc.selection.deselect();

UI Location: Select > Deselect

expand

async : Promise<void>

Expand the selection by the specified amount.

Copy
await doc.selection.expand(42);
Copied to your clipboard
await doc.selection.expand(42);

UI Location: Select > Modify > Expand

Parameters

feather

async : Promise<void>

Feather the edges of the selection by the specified amount. This softening of the selection strength is best viewed as a channel via Quick Mask Mode. Large values might make the selection disappear entirely (.bounds would return null).

Copy
await doc.selection.feather(16);
Copied to your clipboard
await doc.selection.feather(16);

UI Location: Select > Modify > Feather

Parameters

grow

async : Promise<void>

Grow the selection to include all adjacent pixels falling within the specified tolerance range.

Copy
await doc.selection.grow(32);
Copied to your clipboard
await doc.selection.grow(32);

Unsupported modes: Bitmap, RGB 32 bits, Grayscale 32 bits

UI Location: Select > Grow

Parameters

inverse

async : Promise<void>

Set the active selection to the inverse of the current selection. The new active selection will be cropped to the canvas bounds. If the canvas area is fully selected, inverse will result in no active selection. Note also that Artboard bounds are not respected.

Copy
await doc.selection.inverse();
Copied to your clipboard
await doc.selection.inverse();

UI Location: Select > Inverse

load

async : Promise<void>

Load the selection from the specified Channel or Layer. A Layer's pixels' transparency will be used as the selection values. Full opaque pixels yield fully selected pixels.

Copy
await doc.selection.load(doc.channels[3]); // first alpha channel in RGB document
Copied to your clipboard
await doc.selection.load(doc.channels[3]); // first alpha channel in RGB document

UI Locations:

• Select > Load Selection...
• control/command + click on layer thumbnail
• control/command + click on channel thumbnail

For selecting a path please use PathItem.makeSelection

Parameters

makeWorkPath

async : Promise<PathItem>

Create a work path from the active selection.

Copy
await doc.selection.makeWorkPath();
Copied to your clipboard
await doc.selection.makeWorkPath();

UI Location: Paths panel > Make work path icon

Parameters

resizeBoundary

async : Promise<void>

Scale the selection itself in percent. Does not affect the active layer.

Copy
await doc.selection.resizeBoundary(50, 50);
Copied to your clipboard
await doc.selection.resizeBoundary(50, 50);

UI Location: Select > Transform Selection

Parameters

rotateBoundary

async : Promise<void>

Rotate the selection itself clockwise around the given anchor position. Does not affect the active layer.

Copy
await doc.selection.rotateBoundary(90, constants.AnchorPosition.MIDDLECENTER)
Copied to your clipboard
await doc.selection.rotateBoundary(90, constants.AnchorPosition.MIDDLECENTER)

UI Location: Select > Transform Selection

Parameters

save

async : Promise<void>

Save the selection in a new Alpha Channel.

Copy
await doc.selection.save("My Selection");
Copied to your clipboard
await doc.selection.save("My Selection");

UI Location: Select > Save Selection...

Parameters

saveTo

Promise<void>

Save the selection in an existing Alpha Channel (Component Channels are not supported targets).

Copy
// Stores the current selection into an existing alpha channel in RGB document
await doc.selection.saveTo(doc.channels[3]); 

// Performing an intersection operation on an alpha channel in RGB document
await doc.selection.saveTo(doc.channels[3], SelectionType.INTERSECT);
Copied to your clipboard
// Stores the current selection into an existing alpha channel in RGB document
await doc.selection.saveTo(doc.channels[3]); 

// Performing an intersection operation on an alpha channel in RGB document
await doc.selection.saveTo(doc.channels[3], SelectionType.INTERSECT);

Parameters

selectAll

async : Promise<void>

Select the entire canvas.

If the document has artboards, all the pixels of the artboard that contain the active layer will be selected.

If layers across multiple artboards are active, a single rectangular selection will be made, with bounds wrapping them.

If no artboard is active, all artboards will be selected in the same manner. (The resulting selection might be smaller than the canvas bounds.)

Copy
await doc.selection.selectAll();
Copied to your clipboard
await doc.selection.selectAll();

UI Location: Select > All

selectBorder

async : Promise<void>

Create a new selection based on the border of the active selection. The new selection will be an area equivalent to a stroke of that border by the given width in pixels. The result is not limited by canvas bounds.

Copy
await doc.selection.selectBorder(10);
Copied to your clipboard
await doc.selection.selectBorder(10);

UI Location: Select > Modify > Border...

Parameters

selectColumn

async : Promise<void>

Select a single column of pixels.

Copy
await doc.selection.selectColumn(90);
Copied to your clipboard
await doc.selection.selectColumn(90);

UI Location: Toolbar > Single Column Marquee Tool

Parameters

selectEllipse

async : Promise<void>

Make an elliptical selection.

Copy
await doc.selection.selectEllipse({top: 0, left: 0, bottom: 100, right: 100});
Copied to your clipboard
await doc.selection.selectEllipse({top: 0, left: 0, bottom: 100, right: 100});

UI Location: Toolbar > Elliptical Marquee Tool

Parameters

selectPolygon

async : Promise<void>

Make a polygonal selection.

Copy
await doc.selection.selectPolygon([
    {x: 50, y: 10}, 
    {x: 100, y: 90},
    {x: 10, y: 40}
]);
Copied to your clipboard
await doc.selection.selectPolygon([
    {x: 50, y: 10}, 
    {x: 100, y: 90},
    {x: 10, y: 40}
]);

UI Location: Toolbar > Polygonal Lasso Tool

Parameters

selectRectangle

async : Promise<void>

Make a rectangluar selection.

Copy
await doc.selection.selectRectangle(
    {top: 0, left: 0, bottom: 100, right: 100},
    Constants.SelectionType.REPLACE,
    10
);
Copied to your clipboard
await doc.selection.selectRectangle(
    {top: 0, left: 0, bottom: 100, right: 100},
    Constants.SelectionType.REPLACE,
    10
);

UI Location: Toolbar > Rectangular Marquee Tool

Parameters

selectRow

async : Promise<void>

Select a single row of pixels.

Copy
await doc.selection.selectRow(10);
Copied to your clipboard
await doc.selection.selectRow(10);

UI Location: Toolbar > Single Row Marquee Tool

Parameters

smooth

async : Promise<void>

Reduce patchiness and smooth sharp corners and jagged lines in the selection. Smooth will also remove isolated groups of pixels that are smaller than the given radius. This effect is useful for cleaning up stray pixels from color-based selections.

Large values might make the selection disappear entirely (.bounds would return null).

Copy
await doc.selection.smooth(32);
Copied to your clipboard
await doc.selection.smooth(32);

UI Location: Select > Modify > Smooth...

Parameters

translateBoundary

async : Promise<void>

Move the selection itself relative to its current position. Does not affect the active layer.

Copy
await doc.selection.translateBoundary(100, 600);
Copied to your clipboard
await doc.selection.translateBoundary(100, 600);

UI Location: Select > Transform Selection

Parameters

Last updated 9/29/2021

Was this helpful?

Yes

No