Class LayerFacade
Identification Accessors
The key which can be used to name files in the file system. It SHOULD be unique within an artboard.
IDs can include characters invalid for use in file names (such as :
).
Example:
// Safe:
layer.renderToFile(`./layers/${layer.fileKey}.png`)
// Unsafe:
layer.renderToFile(`./layers/${layer.id}.png`)
The ID of the layer.
Beware that this value may not be safely usable for naming files in the file system and the fileKey value should be instead.
Data Accessors
The name of the layer.
Octopus data of the layer.
This data can be used for accessing details about the layer.
See the Octopus Format documentation page for more info.
Example:
const blendMode = layer.octopus['blendMode']
const opacity = layer.octopus['opacity']
const visible = layer.octopus['visible']
const overrides = layer.octopus['overrides']
The type of the layer.
Reference Accessors
The ID of the artboard in which the layer is placed.
Layer Context Accessors
The nesting level at which the layer is contained within the layer tree of the artboard.
Root (first-level) layers have depth of 1.
Example:
const rootLayer = artboard.getRootLayers()[0]
console.log(rootLayer.depth) // 1
const nestedLayer = rootLayer.getNestedLayers()[0]
console.log(nestedLayer.depth) // 2
const deeperNestedLayer = nestedLayer.getNestedLayers()[0]
console.log(deeperNestedLayer.depth) // 3
Data Methods
Returns the attributes of the layer.
Example:
const { blendingMode, opacity, visible } = await layer.getAttributes()
Returns various bounds of the layer.
The rendering engine and the local cache have to be configured when using this method.
Example:
const layerBounds = await layer.getBounds()
const boundsWithEffects = layerBounds.fullBounds
Parameters:
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. the artboards is not uncached when newly cached). A cancellation token can be created via createCancelToken.
Various layer bounds.
Returns a layer effect aggregation object.
Any layer can have various effects (such as shadows, borders or fills) applied to it.
Note that there can be bitmap assets in case of pattern fill effects being applied.
Example:
const effects = layer.getEffects()
const shadows = effects.octopus['shadows']
Returns a text object of the layer if there is one.
Only text layers (type=textLayer
) return text objects here.
Example:
const text = layer.getText()
const textValue = text ? text.getTextContent() : null
Returns the text value of the layer if there is one.
Only text layers (type=textLayer
) return text objects here. This is a shortcut for .getText()?.getTextContent()
Example:
const textValue = layer.getTextContent()
Reference Methods
Returns the artboard object associated with the layer object.
Example:
const artboard = layer.getArtboard()
Returns the artboard which represents the main/master component of which this layer is and instance.
Nothing is returned from layers which do not represent a component (instance), see isComponentInstance.
Example:
const componentArtboard = layer.getComponentArtboard()
Layer Context Methods
Returns whether there are any overrides on this component (instance) which override main/master component values.
The specific overrides can be obtained from the octopus data (octopus.overrides
).
Layers which do not represent a component (instance), see isComponentInstance, return false
.
Example:
if (layer.hasComponentOverrides()) {
const overrides = layer.octopus['overrides']
}
Returns whether the layer is a component (instance of a main/master component).
Example:
if (layer.isComponentInstance()) {
console.log(layer.getComponentArtboard()) // Artboard
}
Returns whether the layer represents an "inline artboard" (which is a feature used in Photoshop design files only).
Example:
const isInline = layer.isInlineArtboard()
Returns whether the layer is masked/clipped by another layer.
Example:
if (layer.isMasked()) {
layer.getMaskLayerId() // <MASK_ID>
layer.getMaskLayer() // Layer { id: '<MASK_ID>' }
} else {
layer.getMaskLayerId() // null
layer.getMaskLayer() // null
}
Returns whether the layer is located at the first level within the layer tree of the artboard (i.e. it does not have a parent layer).
Example:
const root = layer.isRootLayer()
Layer Lookup Methods
Returns the first layer object nested within the layer (i.e. the layer is either the immediate parent layer of other layers or one of their parent layers), optionally down to a specific layer nesting level, which matches the specific criteria.
Note that the subtree is walked in document order, not level by level, which means that nested layers of a layer are searched before searching sibling layers of the layer.
Example:
// Layer tree:
// a {
// b1 { c1, c2 },
// b2 { c3 }
// }
const layerA = artboard.getLayerById('a')
// All nesting levels
console.log(layerA.findNestedLayer({ id: 'c1' }))
// Layer { id: 'c1' },
// Immediate nesting level
console.log(layerA.findNestedLayer({ id: 'c1', depth: 0 }))
// null
// Function selectors
console.log(layerA.findNestedLayer((layer) => {
return layer.id === 'c1'
}))
// Layer { id: 'c1' },
Parameters:
A layer selector. All specified fields must be matched by the result.
Options
The maximum nesting level within the layer to search. By default, all levels are searched. 0
also means "no limit"; 1
means only layers nested directly in the layer should be searched.
A matched layer object.
Returns a collection of layer objects nested within the layer (i.e. the layer is either the immediate parent layer of other layers or one of their parent layers), optionally down to a specific layer nesting level, which match the specific criteria.
Note that the results are sorted in document order, not level by level, which means that matching nested layers of a layer are included before matching sibling layers of the layer.
Example:
// Layer tree:
// a {
// b1 { c1, c2 },
// b2 { c3 }
// }
const layerA = artboard.getLayerById('a')
// All nesting levels
console.log(layerA.findNestedLayers({ id: ['b1', 'c1', 'c3'] }))
// DesignLayerCollection [
// Layer { id: 'b1' },
// Layer { id: 'c1' },
// Layer { id: 'c3' },
// ]
// Immediate nesting level
console.log(layerA.findNestedLayers({ id: ['b1', 'c1', 'c3'], depth: 0 }))
// DesignLayerCollection [ Layer { id: 'b1' } ]
// Function selectors
console.log(layerA.findNestedLayers((layer) => {
return layer.id === 'b1' || layer.id === 'c1'
}))
// DesignLayerCollection [ Layer { id: 'b1' }, Layer { id: 'c1' } ]
Parameters:
A layer selector. All specified fields must be matched by the result.
Options
The maximum nesting level within the layer to search. By default, all levels are searched. 0
also means "no limit"; 1
means only layers nested directly in the layer should be searched.
A collection of matched layers.
Returns the deepest parent layer objects which contains the layer and matches the provided criteria.
Example:
const rootLayer = artboard.getRootLayers()[0]
// Layer { id: 'x', type: 'groupLayer', name: 'A' }
const nestedLayer1 = rootLayer.getNestedLayers()[0]
// Layer { id: 'y', type: 'groupLayer', name: 'B' }
const nestedLayer2 = nestedLayer1.getNestedLayers()[0]
// Layer { id: 'z', type: 'groupLayer', name: 'A' }
console.log(nestedLayer2.findParentLayer({ name: 'A' })) // Layer { id: 'z' }
Parameters:
A parent layer selector.
A matched parent layer object.
Returns all parent layer objects which contain the layer and match the provided criteria sorted from the immediate parent layer to the first-level (root) layer.
Example:
const rootLayer = artboard.getRootLayers()[0]
// Layer { id: 'x', type: 'groupLayer', name: 'A' }
const nestedLayer1 = rootLayer.getNestedLayers()[0]
// Layer { id: 'y', type: 'groupLayer', name: 'B' }
const nestedLayer2 = nestedLayer1.getNestedLayers()[0]
// Layer { id: 'z', type: 'groupLayer', name: 'A' }
console.log(nestedLayer2.findParentLayers({ name: 'A' }))
// DesignLayerCollection [ Layer { id: 'z' }, Layer { id: 'x' } ]
Parameters:
A parent layer selector.
A collection of matched parent layer objects.
Returns the layer which masks/clips the layer if there is one.
Example:
layer.getMaskLayer() // Layer { id: '<MASK_ID>' }
layer.getMaskLayerId() // <MASK_ID>
Returns the ID of the layer which masks/clips the layer if there is one.
Example:
const maskLayerId = layer.getMaskLayerId()
Returns a collection of layer objects nested within the layer (i.e. the layer is either the immediate parent layer of other layers or one of their parent layers), optionally down to a specific layer nesting level.
This usually applies to group layers and expanded/inlined component layers. Empty group layers return an empty nested layer collection.
Note that, in case of depth
other than 1, the subtree is flattened in document order, not level by level, which means that nested layers of a layer are included before sibling layers of the layer.
Example:
// Layer tree:
// a {
// b1 { c1, c2 },
// b2 { c3 }
// }
const layerA = artboard.getLayerById('a')
// Immediate nesting level
console.log(layerA.getNestedLayers())
// DesignLayerCollection [ Layer { id: 'b1' }, Layer { id: 'b2' } ]
// All nesting levels
console.log(layerA.getNestedLayers({ depth: 0 }))
// DesignLayerCollection [
// Layer { id: 'b1' },
// Layer { id: 'c1' },
// Layer { id: 'c2' },
// Layer { id: 'b2' },
// Layer { id: 'c3' },
// ]
Parameters:
Options
The maximum nesting level within the layer to include in the collection. By default, only the immediate nesting level is included. Infinity
can be specified to get all nesting levels.
A collection of nested layers.
Returns the immediate parent layer object which contains the layer.
Example:
const rootLayer = artboard.getRootLayers()[0]
rootLayer.getParentLayer() // null
const nestedLayer = rootLayer.getNestedLayers()[0]
nestedLayer.getParentLayer() // rootLayer
const deeperNestedLayer = nestedLayer.getNestedLayers()[0]
deeperNestedLayer.getParentLayer() // nestedLayer
Returns the IDs of all parent layers which contain the layer sorted from the immediate parent layer to the first-level (root) layer.
Example:
const rootLayer = artboard.getRootLayers()[0]
rootLayer.getParentLayerIds() // []
const nestedLayer = rootLayer.getNestedLayers()[0]
nestedLayer.getParentLayerIds() // [rootLayer.id]
const deeperNestedLayer = nestedLayer.getNestedLayers()[0]
deeperNestedLayer.getParentLayerIds() // [nestedLayer.id, rootLayer.id]
Returns all parent layer objects which contain the layer sorted from the immediate parent layer to the first-level (root) layer.
Example:
const rootLayer = artboard.getRootLayers()[0]
rootLayer.getParentLayers() // DesignLayerCollection []
const nestedLayer = rootLayer.getNestedLayers()[0]
nestedLayer.getParentLayers() // DesignLayerCollection [rootLayer]
const deeperNestedLayer = nestedLayer.getNestedLayers()[0]
deeperNestedLayer.getParentLayers() // DesignLayerCollection [nestedLayer, rootLayer]
Returns whether there are any layers nested within the layer (i.e. the layer is the parent layer of other layers).
This usually applies to group layers and expanded/inlined component layers. Empty group layers return false
.
Example:
if (layer.hasNestedLayers()) {
console.log(layer.getNestedLayers()) // DesignLayerCollection [ ...(layers)... ]
} else {
console.log(layer.getNestedLayers()) // DesignLayerCollection []
}
Returns whether the layer matches the provided selector.
Example:
console.log(layer.name) // A
layer.matches({ name: 'A' }) // true
console.log(layer.getText().getTextContent()) // This is text.
layer.matches({ text: 'This is text.' }) // true
Parameters:
The selector against which to test the layer.
Whether the layer matches.
Asset Methods
Returns the bitmap asset of the layer if there is one.
Example:
const bitmap = layer.getBitmap()
const bitmapAssetName = bitmap?.getBitmapAssetName()
Returns a list of bitmap assets used by the layer and layers nested within the layer (optionally down to a specific nesting level).
Note that this method aggregates results of the more granular bitmap asset-related methods of getBitmap}.
Example:
// Bitmap assets from the layer and all its nested layers
const bitmapAssetDescs = await layer.getBitmapAssets()
Parameters:
Options
The maximum nesting level within the layer to search for bitmap asset usage. By default, all levels are searched. Specifying the depth of 0
leads to nested layer bitmap assets being omitted altogether.
Whether to also include "pre-rendered" bitmap assets. These assets can be produced by the rendering engine (if configured; future functionality) but are available as assets for either performance reasons or due to the some required data (such as font files) potentially not being available. By default, pre-rendered assets are included.
A list of bitmap assets.
Returns the bitmap mask of the layer if there is one.
Example:
const bitmapMask = layer.getBitmapMask()
const bitmapMaskAssetName = bitmapMask?.getBitmap().getBitmapAssetName()
Returns a list of fonts used by the layer and layers nested within the layer (optionally down to a specific nesting level).
Example:
// Fonts from the layer and all its nested layers
const fontDescs = await layer.getFonts()
Parameters:
Options
The maximum nesting level within page and artboard layers to search for font usage. By default, all levels are searched. Specifying the depth of 0
leads to fonts used by nested layers being omitted altogether.
A list of fonts.
Returns whether the bitmap asset is "pre-rendered".
Only non-bitmap layers (type!=layer
) have prerendered assets. Bitmap assets of bitmap layers are not considered "pre-rendered".
Example:
const prerendered = layer.isBitmapPrerendered()
const originalBitmap = prerendered ? null : layer.getBitmap()
Rendering Methods
Renders the layer as an PNG image file.
In case the layer is a group layer, all visible nested layers are also included.
Uncached items (bitmap assets of rendered layers) are downloaded and cached.
The rendering engine and the local cache have to be configured when using this method.
Example:
With default options (1x, whole layer area)
await layer.renderToFile(
'./rendered/layer.png'
)
With custom scale and crop and using the component background color
await layer.renderToFile(
'./rendered/layer.png',
{
scale: 2,
// The result is going to have the dimensions of 400x200 due to the 2x scale.
bounds: { left: 100, top: 0, width: 100, height: 50 },
includeComponentBackground: true,
}
)
Parameters:
The target location of the produced PNG image file.
Render options
The blending mode to use for rendering the layer instead of its default blending mode.
The area to include. This can be used to either crop or expand (add empty space to) the default layer area.
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. the created image file is not deleted when cancelled during actual rendering). A cancellation token can be created via createCancelToken.
Whether to apply clipping by a mask layer if any such mask is set for the layer (see isMasked). Clipping is disabled by default. Setting this flag for layers which do not have a mask layer set has no effect on the results.
Whether to render the component background from the main/master component. By default, the configuration from the main/master component is used. Note that this configuration has no effect when the artboard background is not included via explicit includeComponentBackground=true
nor the main/master component configuration as there is nothing with which to blend the layer.
Whether to apply layer effects of the layer. Rendering of effects of nested layers is not affected. By defaults, effects of the layer are applied.
The opacity to use for the layer instead of its default opacity.
The scale (zoom) factor to use for rendering instead of the default 1x factor.
SVG export Methods
Returns an SVG document string of the layer.
In case the layer is a group layer, all visible nested layers are also included.
Bitmap assets are serialized as base64 data URIs.
Uncached items (bitmap assets of rendered layers) are downloaded and cached.
The SVG exporter has to be configured when using this methods. The local cache has to also be configured when working with layers with bitmap assets.
Example:
With default options (1x)
const svg = await layer.exportToSvgCode()
With custom scale and opacity
const svg = await layer.exportToSvgCode({
opacity: 0.6,
scale: 2,
})
Parameters:
Export options
The blending mode to use for rendering the layer instead of its default blending mode.
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. the created image file is not deleted when cancelled during actual rendering). A cancellation token can be created via createCancelToken.
Whether to apply clipping by a mask layer if any such mask is set for the layer (see isMasked). Clipping is disabled by default. Setting this flag for layers which do not have a mask layer set has no effect on the results.
Whether to apply layer effects of the layer. Rendering of effects of nested layers is not affected. By defaults, effects of the layer are applied.
The opacity to use for the layer instead of its default opacity.
The scale (zoom) factor to use for rendering instead of the default 1x factor.
An SVG document string.
Export the layer as an SVG file.
In case the layer is a group layer, all visible nested layers are also included.
Bitmap assets are serialized as base64 data URIs.
Uncached items (bitmap assets of rendered layers) are downloaded and cached.
The SVG exporter has to be configured when using this methods. The local cache has to also be configured when working with layers with bitmap assets.
Example:
With default options (1x)
await layer.exportToSvgFile('./layer.svg')
With custom scale and opacity
await layer.exportToSvgFile('./layer.svg', {
opacity: 0.6,
scale: 2,
})
Parameters:
The target location of the produced SVG file.
Export options
The blending mode to use for rendering the layer instead of its default blending mode.
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. the created image file is not deleted when cancelled during actual rendering). A cancellation token can be created via createCancelToken.
Whether to apply clipping by a mask layer if any such mask is set for the layer (see isMasked). Clipping is disabled by default. Setting this flag for layers which do not have a mask layer set has no effect on the results.
Whether to apply layer effects of the layer. Rendering of effects of nested layers is not affected. By defaults, effects of the layer are applied.
The opacity to use for the layer instead of its default opacity.
The scale (zoom) factor to use for rendering instead of the default 1x factor.
Was this article helpful?