Open Design

Class ArtboardFacade

Identification Accessors

fileKey
get fileKey(): string

The key which can be used to name files in the file system. It SHOULD be unique within a design.

IDs can include characters invalid for use in file names (such as :).

Example:

// Safe:
artboard.renderToFile(`./artboards/${artboard.fileKey}.png`)

// Unsafe:
artboard.renderToFile(`./artboards/${artboard.id}.png`)
returns string
id
get id(): string

The ID of the artboard.

Beware that this value may not be safely usable for naming files in the file system and the fileKey value should be instead.

returns string
name
get name(): null | string

The name of the artboard.

returns null | string

Reference Accessors

componentId
get componentId(): null | string

The ID of the component this artboard represents.

returns null | string
pageId
get pageId(): null | string

The ID of the page in which the artboard is placed.

returns null | string

Data Methods

getBackgroundColor
getBackgroundColor(options?: { cancelToken?: null | CancelToken }): Promise<null | { a: number; b: number; g: number; r: number }>

Returns the background color of the artboard.

This method internally triggers loading of the artboard content. In case the artboard is uncached, it is downloaded (and cached when the local cache is configured). The API has to be configured when working with an uncached artboard.

Example:

const color = await artboard.getBackgroundColor()
if (color) {
  console.log(color) // { r: number, g: number, b: number, a: number }
}

Parameters:

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<null | { a: number; b: number; g: number; r: number }>

The background color.

getBounds
getBounds(options?: { cancelToken?: null | CancelToken }): Promise<Bounds>

Returns the dimensions of the artboard and its position within the coordinate system of the design/page.

Example:

const artboardBounds = await artboard.getBounds()

Parameters:

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<Bounds>

The artboard bounds.

getContent
getContent(options?: { cancelToken?: null | CancelToken }): Promise<OctopusDocument>

Returns the content of the artboard in the form of an "artboard octopus" document.

This data includes the list of layers, the artboard position and size as well as styles used in the artboard.

See the Octopus Format documentation page for more info.

This method internally triggers loading of the artboard content. In case the artboard is uncached, it is downloaded (and cached when the local cache is configured). The API has to be configured when working with an uncached artboard.

Example:

const artboardContent = await artboards.getContent()

Parameters:

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<OctopusDocument>

The artboard content.

getLayerAttributes
getLayerAttributes(layerId: string, options?: { cancelToken?: null | CancelToken }): Promise<LayerAttributes>

Returns the attributes of the specified layer.

Example:

const { blendingMode, opacity, visible } = await layer.getLayerAttributes('<LAYER_ID>')

Parameters:

layerId: string

The ID of the layer to inspect.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<LayerAttributes>

An SVG document string.

getLayerBounds
getLayerBounds(layerId: string, options?: { cancelToken?: null | CancelToken }): Promise<LayerBounds>

Returns various bounds of the specified layer.

The rendering engine and the local cache have to be configured when using this method.

Example:

const layerBounds = await artboard.getLayerBounds('<LAYER_ID>')
const boundsWithEffects = layerBounds.fullBounds

Parameters:

layerId: string

The ID of the artboard layer to inspect.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<LayerBounds>

Various layer bounds.

isComponent
isComponent(): boolean

Returns whether the artboard represends a (main/master) component.

Example:

const isComponentArtboard = artboard.isComponent()
returns boolean

Reference Methods

getDesign
getDesign(): DesignFacade

Returns the design object associated with the artboard object.

Example:

const design = artboard.getDesign()
returns DesignFacade
getPage
getPage(): null | PageFacade

Returns the page object associated with the artboard object.

Example:

const page = artboard.getPage()
returns null | PageFacade

Layer Lookup Methods

findLayer
findLayer(selector: LayerSelector | (layer: LayerFacade) => boolean, options?: { cancelToken?: null | CancelToken; depth?: number }): Promise<null | LayerFacade>

Returns the first layer object from the artboard (optionally down to a specific nesting level) matching the specified criteria.

This method internally triggers loading of the artboard content. In case the artboard is uncached, it is downloaded (and cached when the local cache is configured). The API has to be configured when working with an uncached artboard.

Example:

Layer by name

const layer = await artboard.findLayer({ name: 'Share icon' })

Layer by function selector

const shareIconLayer = await design.findLayer((layer) => {
  return layer.name === 'Share icon'
})

Text layer by content

const layer = await artboard.findLayer({
  type: 'textLayer',
  text: /click to dismiss/i,
})

With timeout

const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layer = await artboard.findLayer(
  { name: 'Share icon' },
  { cancelToken: token }
)

Parameters:

selector: LayerSelector | (layer: LayerFacade) => boolean

A layer selector. All specified fields must be matched by the result.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionaldepth?: number

The maximum nesting level within page and artboard layers to search. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in the artboard should be searched.

returns Promise<null | LayerFacade>

A layer object.

findLayers
findLayers(selector: LayerSelector | (layer: LayerFacade) => boolean, options?: { cancelToken?: null | CancelToken; depth?: number }): Promise<LayerCollectionFacade>

Returns a collection of all layer objects from the artboards (optionally down to a specific nesting level) matching the specified criteria.

This method internally triggers loading of the artboard content. In case the artboard is uncached, it is downloaded (and cached when the local cache is configured). The API has to be configured when working with an uncached artboard.

Example:

Layer by name

const layer = await artboard.findLayers({ name: 'Share icon' })

Layers by function selector

const shareIconLayers = await design.findLayers((layer) => {
  return layer.name === 'Share icon'
})

Invisible text layers

const layer = await artboard.findLayers({
  type: 'textLayer',
  visible: false,
})

With timeout

const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layer = await artboard.findLayers(
  { name: 'Share icon' },
  { cancelToken: token }
)

Parameters:

selector: LayerSelector | (layer: LayerFacade) => boolean

A layer selector. All specified fields must be matched by the result.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionaldepth?: number

The maximum nesting level within page and artboard layers to search. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in the artboard should be searched.

returns Promise<LayerCollectionFacade>

A layer collection with layer matches.

getFlattenedLayers
getFlattenedLayers(options?: { cancelToken?: null | CancelToken; depth?: number }): Promise<LayerCollectionFacade>

Returns a collection of all layers from the artboard (optionally down to a specific nesting level).

The produced collection can be queried further for narrowing down the search.

This method internally triggers loading of the artboard content. In case the artboard is uncached, it is downloaded (and cached when the local cache is configured). The API has to be configured when working with an uncached artboard.

Example:

All layers (from all nesting levels)

const allLayers = await artboard.getFlattenedLayers()

Layers from the first three nesting levels (root layers + 2 levels)

const layers = await artboard.getFlattenedLayers({ depth: 3 })

Parameters:

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionaldepth?: number

The maximum nesting level of layers within the artboard to include in the collection. By default, all levels are included. 0 also means "no limit"; 1 means only root layers in the artboard should be included.

returns Promise<LayerCollectionFacade>

A collection of flattened layers.

getLayerAtPosition
getLayerAtPosition(x: number, y: number, options?: { cancelToken?: null | CancelToken }): Promise<null | LayerFacade>

Returns the top-most layer located at the specified coordinates within the specified artboard.

The rendering engine and the local cache have to be configured when using this method.

Example:

const layerId = await artboard.getLayerAtPosition(100, 200)

Parameters:

x: number

The X coordinate in the coordinate system of the artboard where to look for a layer.

y: number

The Y coordinate in the coordinate system of the artboard where to look for a layer.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<null | LayerFacade>

A layer object.

getLayerById
getLayerById(layerId: string, options?: { cancelToken?: null | CancelToken }): Promise<null | LayerFacade>

Returns the layer object from within the artboard which has the specified ID.

Layer IDs are unique within individual artboards.

This method internally triggers loading of the artboard content. In case the artboard is uncached, it is downloaded (and cached when the local cache is configured). The API has to be configured when working with an uncached artboard.

Example:

Single layer

const layerA = await artboard.getLayerById('a')

Multiple layers

const [ layerA, layerB, layerC ] = await Promise.all([
  artboard.getLayerById('a'),
  artboard.getLayerById('b'),
  artboard.getLayerById('c'),
])

Parameters:

layerId: string

A layer ID.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<null | LayerFacade>

A layer object.

getLayerDepth
getLayerDepth(layerId: string, options?: { cancelToken?: null | CancelToken }): Promise<null | number>

Returns the nesting level at which the layer of the specified ID is contained within the layer tree of the artboard.

This method internally triggers loading of the artboard content. In case the artboard is uncached, it is downloaded (and cached when the local cache is configured). The API has to be configured when working with an uncached artboard.

Example:

const depth = await artboard.getLayerDepth('<ARTBOARD_ID>', '<LAYER_ID>')

Parameters:

layerId: string

A layer ID.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<null | number>

The depth where the layer is located within the layer tree of the artboard. Root layers have the depth of 1.

getLayersInArea
getLayersInArea(bounds: Bounds, options?: { cancelToken?: null | CancelToken; partialOverlap?: boolean }): Promise<Array<LayerFacade>>

Returns all layers located within the specified area of the the specified artboard.

The rendering engine and the local cache have to be configured when using this method.

Example:

const layerIds = await artboard.getLayersInArea(
  { left: 80, top: 150, width: 40, height: 30 }
)
const layerIds = await artboard.getLayersInArea(
  { left: 80, top: 150, width: 40, height: 30 },
  { partialOverlap: true }
)

Parameters:

bounds: Bounds

The area in the corrdinate system of the artboard where to look for layers.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

OptionalpartialOverlap?: boolean

Whether to also return layers which are only partially contained within the specified area.

returns Promise<Array<LayerFacade>>

Array of layer objects.

getRootLayers
getRootLayers(options?: { cancelToken?: null | CancelToken }): Promise<LayerCollectionFacade>

Returns a collection of the first-level (root) layers objects within the artboard.

This method internally triggers loading of the artboard content. In case the artboard is uncached, it is downloaded (and cached when the local cache is configured). The API has to be configured when working with an uncached artboard.

Example:

const rootLayers = await artboard.getRootLayers()

Parameters:

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<LayerCollectionFacade>

A collection of root layers.

Asset Methods

getBitmapAssets
getBitmapAssets(options?: { cancelToken?: null | CancelToken; depth?: number; includePrerendered?: boolean }): Promise<Array<BitmapAssetDescriptor & { artboardLayerIds: Record<string, Array<string>> }>>

Returns a list of bitmap assets used by layers in the artboard (optionally down to a specific nesting level).

This method internally triggers loading of the artboard content. In case the artboard is uncached, it is downloaded (and cached when the local cache is configured). The API has to be configured when working with an uncached artboard.

Example:

// All bitmap assets from the artboard
const bitmapAssetDescs = await artboard.getBitmapAssets()

// Bitmap assets excluding pre-renredered bitmaps from the artboard
const bitmapAssetDescs = await artboard.getBitmapAssets({
  includePrerendered: false,
})

Parameters:

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionaldepth?: number

The maximum nesting level within page and artboard layers to search for bitmap asset usage. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in the artboard should be searched.

OptionalincludePrerendered?: boolean

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.

returns Promise<Array<BitmapAssetDescriptor & { artboardLayerIds: Record<string, Array<string>> }>>

A list of bitmap assets.

getFonts
getFonts(options?: { cancelToken?: null | CancelToken; depth?: number }): Promise<Array<FontDescriptor & { artboardLayerIds: Record<string, Array<string>> }>>

Returns a list of fonts used by layers the artboard (optionally down to a specific nesting level).

This method internally triggers loading of the artboard content. In case the artboard is uncached, it is downloaded (and cached when the local cache is configured). The API has to be configured when working with an uncached artboard.

Example:

// All fonts from the artboard
const fontDescs = await artboard.getFonts()

Parameters:

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionaldepth?: number

The maximum nesting level within page and artboard layers to search for font usage. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in the artboard should be searched.

returns Promise<Array<FontDescriptor & { artboardLayerIds: Record<string, Array<string>> }>>

A list of fonts.

Rendering Methods

renderLayerToFile
renderLayerToFile(layerId: string, filePath: string, options?: { blendingMode?: "BLEND_DIVIDE" | "BLEND_SUBTRACTION" | "COLOR" | "COLOR_BURN" | "COLOR_DODGE" | "DARKEN" | "DARKER_COLOR" | "DIFFERENCE" | "DISSOLVE" | "EXCLUSION" | "HARD_LIGHT" | "HARD_MIX" | "HUE" | "LIGHTEN" | "LIGHTER_COLOR" | "LIGHTEN_BURN" | "LIGHTEN_DODGE" | "LIGHTEN_LIGHT" | "LUMINOSITY" | "MULTIPLY" | "OVERLAY" | "PASS_THROUGH" | "PIN_LIGHT" | "SATURATION" | "SCREEN" | "SOFT_LIGHT" | "VIVID_LIGHT" | "NORMAL"; bounds?: Bounds; cancelToken?: null | CancelToken; clip?: boolean; includeComponentBackground?: boolean; includeEffects?: boolean; opacity?: number; scale?: number }): Promise<void>

Renders the specified layer from the artboard as an PNG image file.

In case of group layers, all visible nested layers are also included.

Uncached items (artboard content and 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 artboard.renderLayerToFile(
  '<LAYER_ID>',
  './rendered/layer.png'
)

With custom scale and crop and using the component background color

await artboard.renderLayerToFile(
  '<LAYER_ID>',
  './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:

layerId: string

The ID of the artboard layer to render.

filePath: string

The target location of the produced PNG image file.

options: default: {}

Options

OptionalblendingMode?: "BLEND_DIVIDE" | "BLEND_SUBTRACTION" | "COLOR" | "COLOR_BURN" | "COLOR_DODGE" | "DARKEN" | "DARKER_COLOR" | "DIFFERENCE" | "DISSOLVE" | "EXCLUSION" | "HARD_LIGHT" | "HARD_MIX" | "HUE" | "LIGHTEN" | "LIGHTER_COLOR" | "LIGHTEN_BURN" | "LIGHTEN_DODGE" | "LIGHTEN_LIGHT" | "LUMINOSITY" | "MULTIPLY" | "OVERLAY" | "PASS_THROUGH" | "PIN_LIGHT" | "SATURATION" | "SCREEN" | "SOFT_LIGHT" | "VIVID_LIGHT" | "NORMAL"

The blending mode to use for rendering the layer instead of its default blending mode.

Optionalbounds?: Bounds

The area to include. This can be used to either crop or expand (add empty space to) the default layer area.

OptionalcancelToken?: null | CancelToken

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.

Optionalclip?: boolean

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.

OptionalincludeComponentBackground?: boolean

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.

OptionalincludeEffects?: boolean

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.

Optionalopacity?: number

The opacity to use for the layer instead of its default opacity.

Optionalscale?: number

The scale (zoom) factor to use for rendering instead of the default 1x factor.

returns Promise<void>
renderLayersToFile
renderLayersToFile(layerIds: Array<string>, filePath: string, options?: { bounds?: Bounds; cancelToken?: null | CancelToken; layerAttributes?: Record<string, LayerAttributesConfig>; scale?: number }): Promise<void>

Renders the specified layers from the artboard as a single PNG image file.

In case of group layers, all visible nested layers are also included.

Uncached items (artboard content and 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 combined layer area)

await artboard.renderLayersToFile(
  ['<LAYER1>', '<LAYER2>'],
  './rendered/layers.png'
)

With custom scale and crop and using the custom layer configuration

await artboard.renderLayersToFile(
  ['<LAYER1>', '<LAYER2>'],
  './rendered/layers.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 },
    layerAttributes: {
      '<LAYER1>': { blendingMode: 'SOFT_LIGHT', includeComponentBackground: true },
      '<LAYER2>': { opacity: 0.6 },
    }
  }
)

Parameters:

layerIds: Array<string>

The IDs of the artboard layers to render.

filePath: string

The target location of the produced PNG image file.

options: default: {}

Options

Optionalbounds?: Bounds

The area to include. This can be used to either crop or expand (add empty space to) the default layer area.

OptionalcancelToken?: null | CancelToken

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.

OptionallayerAttributes?: Record<string, LayerAttributesConfig>

Layer-specific options to use for the rendering instead of the default values.

Optionalscale?: number

The scale (zoom) factor to use for rendering instead of the default 1x factor.

returns Promise<void>
renderToFile
renderToFile(filePath: string, options?: { cancelToken?: null | CancelToken; scale?: number }): Promise<void>

Renders the artboard as an PNG image file.

All visible layers from the artboard are included.

Uncached items (artboard content and 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 artboard area)

await artboard.renderToFile('./rendered/artboard.png')

With custom scale and crop

await artboard.renderToFile('./rendered/artboard.png', {
  scale: 4,
  // The result is going to have the dimensions of 400x200 due to the 4x scale.
  bounds: { left: 100, top: 0, width: 100, height: 50 },
})

Parameters:

filePath: string

The target location of the produced PNG image file.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionalscale?: number

The scale (zoom) factor to use for rendering instead of the default 1x factor.

returns Promise<void>

SVG Export Methods

exportLayerToSvgCode
exportLayerToSvgCode(layerId: string, options?: { blendingMode?: "BLEND_DIVIDE" | "BLEND_SUBTRACTION" | "COLOR" | "COLOR_BURN" | "COLOR_DODGE" | "DARKEN" | "DARKER_COLOR" | "DIFFERENCE" | "DISSOLVE" | "EXCLUSION" | "HARD_LIGHT" | "HARD_MIX" | "HUE" | "LIGHTEN" | "LIGHTER_COLOR" | "LIGHTEN_BURN" | "LIGHTEN_DODGE" | "LIGHTEN_LIGHT" | "LUMINOSITY" | "MULTIPLY" | "OVERLAY" | "PASS_THROUGH" | "PIN_LIGHT" | "SATURATION" | "SCREEN" | "SOFT_LIGHT" | "VIVID_LIGHT" | "NORMAL"; cancelToken?: null | CancelToken; clip?: boolean; includeEffects?: boolean; opacity?: number; scale?: number }): Promise<string>

Returns an SVG document string of the specified layer from the artboard.

In case of group layers, all visible nested layers are also included.

Bitmap assets are serialized as base64 data URIs.

Uncached items (artboard content and bitmap assets of exported 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)

const svg = await artboard.exportLayerToSvgCode('<LAYER_ID>')

With custom scale and opacity

const svg = await artboard.exportLayerToSvgCode('<LAYER_ID>', { scale: 2 })

Parameters:

layerId: string

The ID of the artboard layer to export.

options: default: {}

Export options

OptionalblendingMode?: "BLEND_DIVIDE" | "BLEND_SUBTRACTION" | "COLOR" | "COLOR_BURN" | "COLOR_DODGE" | "DARKEN" | "DARKER_COLOR" | "DIFFERENCE" | "DISSOLVE" | "EXCLUSION" | "HARD_LIGHT" | "HARD_MIX" | "HUE" | "LIGHTEN" | "LIGHTER_COLOR" | "LIGHTEN_BURN" | "LIGHTEN_DODGE" | "LIGHTEN_LIGHT" | "LUMINOSITY" | "MULTIPLY" | "OVERLAY" | "PASS_THROUGH" | "PIN_LIGHT" | "SATURATION" | "SCREEN" | "SOFT_LIGHT" | "VIVID_LIGHT" | "NORMAL"

The blending mode to use for the layer instead of its default blending mode.

OptionalcancelToken?: null | CancelToken

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.

Optionalclip?: boolean

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.

OptionalincludeEffects?: boolean

Whether to apply layer effects of the layer. Effects of nested layers are not affected. By defaults, effects of the layer are applied.

Optionalopacity?: number

The opacity to use for the layer instead of its default opacity.

Optionalscale?: number

The scale (zoom) factor to use instead of the default 1x factor.

returns Promise<string>

An SVG document string.

exportLayerToSvgFile
exportLayerToSvgFile(layerId: string, filePath: string, options?: { blendingMode?: "BLEND_DIVIDE" | "BLEND_SUBTRACTION" | "COLOR" | "COLOR_BURN" | "COLOR_DODGE" | "DARKEN" | "DARKER_COLOR" | "DIFFERENCE" | "DISSOLVE" | "EXCLUSION" | "HARD_LIGHT" | "HARD_MIX" | "HUE" | "LIGHTEN" | "LIGHTER_COLOR" | "LIGHTEN_BURN" | "LIGHTEN_DODGE" | "LIGHTEN_LIGHT" | "LUMINOSITY" | "MULTIPLY" | "OVERLAY" | "PASS_THROUGH" | "PIN_LIGHT" | "SATURATION" | "SCREEN" | "SOFT_LIGHT" | "VIVID_LIGHT" | "NORMAL"; cancelToken?: null | CancelToken; clip?: boolean; includeEffects?: boolean; opacity?: number; scale?: number }): Promise<void>

Returns an SVG document string of the specified layer from the artboard.

In case of group layers, all visible nested layers are also included.

Bitmap assets are serialized as base64 data URIs.

Uncached items (artboard content and bitmap assets of exported 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)

await artboard.exportLayerToSvgFile('<LAYER_ID>', './layer.svg')

With custom scale and opacity

await artboard.exportLayerToSvgFile(
  '<LAYER_ID>',
  './layer.svg',
  { scale: 2 }
)

Parameters:

layerId: string

The ID of the artboard layer to export.

filePath: string

The target location of the produced SVG file.

options: default: {}

Export options

OptionalblendingMode?: "BLEND_DIVIDE" | "BLEND_SUBTRACTION" | "COLOR" | "COLOR_BURN" | "COLOR_DODGE" | "DARKEN" | "DARKER_COLOR" | "DIFFERENCE" | "DISSOLVE" | "EXCLUSION" | "HARD_LIGHT" | "HARD_MIX" | "HUE" | "LIGHTEN" | "LIGHTER_COLOR" | "LIGHTEN_BURN" | "LIGHTEN_DODGE" | "LIGHTEN_LIGHT" | "LUMINOSITY" | "MULTIPLY" | "OVERLAY" | "PASS_THROUGH" | "PIN_LIGHT" | "SATURATION" | "SCREEN" | "SOFT_LIGHT" | "VIVID_LIGHT" | "NORMAL"

The blending mode to use for the layer instead of its default blending mode.

OptionalcancelToken?: null | CancelToken

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.

Optionalclip?: boolean

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.

OptionalincludeEffects?: boolean

Whether to apply layer effects of the layer. Effects of nested layers are not affected. By defaults, effects of the layer are applied.

Optionalopacity?: number

The opacity to use for the layer instead of its default opacity.

Optionalscale?: number

The scale (zoom) factor to use instead of the default 1x factor.

returns Promise<void>
exportLayersToSvgCode
exportLayersToSvgCode(layerIds: Array<string>, options?: { cancelToken?: null | CancelToken; layerAttributes?: Record<string, LayerOctopusAttributesConfig>; scale?: number }): Promise<string>

Returns an SVG document string of the specified layers from the artboard.

In case of group layers, all visible nested layers are also included.

Bitmap assets are serialized as base64 data URIs.

Uncached items (artboard content and bitmap assets of exported 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)

const svg = await artboard.exportLayersToSvgCode(
  ['<LAYER1>', '<LAYER2>']
)

With a custom scale

const svg = await artboard.exportLayersToSvgCode(
  ['<LAYER1>', '<LAYER2>'],
  {
    scale: 2,
    layerAttributes: {
      '<LAYER1>': { blendingMode: 'SOFT_LIGHT' },
      '<LAYER2>': { opacity: 0.6 },
    }
  }
)

Parameters:

layerIds: Array<string>

The IDs of the artboard layers to render.

options: default: {}

Export options

OptionalcancelToken?: null | CancelToken

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.

OptionallayerAttributes?: Record<string, LayerOctopusAttributesConfig>

Layer-specific options to use for instead of the default values.

Optionalscale?: number

The scale (zoom) factor to use instead of the default 1x factor.

returns Promise<string>

An SVG document string.

exportLayersToSvgFile
exportLayersToSvgFile(layerIds: Array<string>, filePath: string, options?: { cancelToken?: null | CancelToken; layerAttributes?: Record<string, LayerOctopusAttributesConfig>; scale?: number }): Promise<void>

Returns an SVG document string of the specified layers from the artboard.

In case of group layers, all visible nested layers are also included.

Bitmap assets are serialized as base64 data URIs.

Uncached items (artboard content and bitmap assets of exported 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)

await artboard.exportLayersToSvgFile(
  ['<LAYER1>', '<LAYER2>'],
  './layers.svg'
)

With a custom scale

await artboard.exportLayersToSvgFile(
  ['<LAYER1>', '<LAYER2>'],
  './layers.svg',
  {
    scale: 2,
    layerAttributes: {
      '<LAYER1>': { blendingMode: 'SOFT_LIGHT' },
      '<LAYER2>': { opacity: 0.6 },
    }
  }
)

Parameters:

layerIds: Array<string>

The IDs of the artboard layers to render.

filePath: string

The target location of the produced SVG file.

options: default: {}

Export options

OptionalcancelToken?: null | CancelToken

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.

OptionallayerAttributes?: Record<string, LayerOctopusAttributesConfig>

Layer-specific options to use for instead of the default values.

Optionalscale?: number

The scale (zoom) factor to use instead of the default 1x factor.

returns Promise<void>

Artboard Lookup Methods

matches
matches(selector: ArtboardSelector): boolean

Returns whether the artboard matches the provided selector.

Example:

console.log(artboard.name) // A
artboard.matches({ name: 'A' }) // true

Parameters:

The selector against which to test the artboard.

returns boolean

Whether the artboard matches.

Status Methods

isLoaded
isLoaded(): boolean

Returns whether the artboard content is loaded in memory from the API or a local cache.

Example:

const design = await sdk.fetchDesignById('<DESIGN_ID>')
const artboard = design.getArtboardById('<ARTBOARD_ID>')
console.log(artboard.isLoaded()) // false

const layerA = await artboard.findLayerById('a')
console.log(artboard.isLoaded()) // true
returns boolean
unload
unload(): Promise<void>

Releases data related to the artboard from memory.

returns Promise<void>