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.

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

CopyCopied to your clipboard
1const { app, constants } = require("photoshop");
2const doc = app.activeDocument;
3
4await doc.selection.selectRectangle(
5    {top: 50, left: 50, bottom: 100, right: 100},
6    constants.SelectionType.REPLACE
7);
8doc.selection.bounds; // {{top: 50, left: 50, bottom: 100, right: 100}
9doc.selection.solid;  // true
10
11await doc.selection.selectEllipse(
12    {top: 50, left: 70, bottom: 140, right: 100},
13    constants.SelectionType.EXTEND
14);
15doc.selection.bounds; // {top: 50, left: 50, bottom: 140, right: 100}
16doc.selection.solid;  // false
17

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.

await doc.selection.contract(8);
CopyCopied 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.

await doc.selection.deselect();
CopyCopied to your clipboard
await doc.selection.deselect();

UI Location: Select > Deselect

expand

async : Promise<void>

Expand the selection by the specified amount.

await doc.selection.expand(42);
CopyCopied 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).

await doc.selection.feather(16);
CopyCopied 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.

await doc.selection.grow(32);
CopyCopied 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.

await doc.selection.inverse();
CopyCopied 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.

await doc.selection.load(doc.channels[3]); // first alpha channel in RGB document
CopyCopied 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.

await doc.selection.makeWorkPath();
CopyCopied 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.

await doc.selection.resizeBoundary(50, 50);
CopyCopied 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.

await doc.selection.rotateBoundary(90, constants.AnchorPosition.MIDDLECENTER)
CopyCopied 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.

await doc.selection.save("My Selection");
CopyCopied 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).

// 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);
CopyCopied to your clipboard
1// Stores the current selection into an existing alpha channel in RGB document
2await doc.selection.saveTo(doc.channels[3]); 
3
4// Performing an intersection operation on an alpha channel in RGB document
5await 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.)

await doc.selection.selectAll();
CopyCopied 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.

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

UI Location: Select > Modify > Border...

Parameters

selectColumn

async : Promise<void>

Select a single column of pixels.

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

UI Location: Toolbar > Single Column Marquee Tool

Parameters

selectEllipse

async : Promise<void>

Make an elliptical selection.

await doc.selection.selectEllipse({top: 0, left: 0, bottom: 100, right: 100});
CopyCopied 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.

await doc.selection.selectPolygon([
    {x: 50, y: 10}, 
    {x: 100, y: 90},
    {x: 10, y: 40}
]);
CopyCopied to your clipboard
1await doc.selection.selectPolygon([
2    {x: 50, y: 10}, 
3    {x: 100, y: 90},
4    {x: 10, y: 40}
5]);

UI Location: Toolbar > Polygonal Lasso Tool

Parameters

selectRectangle

async : Promise<void>

Make a rectangluar selection.

await doc.selection.selectRectangle(
    {top: 0, left: 0, bottom: 100, right: 100},
    Constants.SelectionType.REPLACE,
    10
);
CopyCopied to your clipboard
1await doc.selection.selectRectangle(
2    {top: 0, left: 0, bottom: 100, right: 100},
3    Constants.SelectionType.REPLACE,
4    10
5);

UI Location: Toolbar > Rectangular Marquee Tool

Parameters

selectRow

async : Promise<void>

Select a single row of pixels.

await doc.selection.selectRow(10);
CopyCopied 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).

await doc.selection.smooth(32);
CopyCopied 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.

await doc.selection.translateBoundary(100, 600);
CopyCopied 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