Open Design

Class DesignFacade

Identification Properties

sourceFilename
null | string

The absolute path of the original design file. This is not available for designs loaded from the API.

Identification Accessors

fileKey
get fileKey(): string

The key which can be used to name files in the file system.

This is the ID of the referenced server-side design or (if the API is not configured) the basename of the local file.

It can theoretically be null when the design is created only virtually in memory but such feature is yet to be implemented thus the value can safely be assumed as always available and for that reason, it is annotated as non-nullable.

Example:

design.renderArtboardToFile(`./artboards/${design.fileKey}/${artboard.fileKey}.png`)
returns string
id
get id(): null | string

The ID of the referenced server-side design. This is not available when the API is not configured for the SDK.

returns null | string

Data Accessors

name
get name(): null | string

The name of the design. This is the basename of the file by default or a custom name provided during design import.

returns null | string

Data Methods

getArtboardBounds
getArtboardBounds(artboardId: string, options?: { cancelToken?: null | CancelToken }): Promise<Bounds>

Returns the bounds of the specified artboard.

The API has to be configured when using this method to get bounds of an uncached artboard.

Example:

const artboardBounds = await design.getArtboardBounds('<ARTBOARD_ID>')

Parameters:

artboardId: string

The ID of the artboard 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. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.

returns Promise<Bounds>

The artboard bounds.

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

Returns the attributes of the spececified layer.

Example:

const attrs = await design.getArtboardLayerAttributes('<ARTBOARD_ID>', '<LAYER_ID>')
const { blendingMode, opacity, visible } = attrs

Parameters:

artboardId: string

The ID of the artboard from which to inspect the layer.

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. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.

returns Promise<LayerAttributes>

Layer attributes.

getArtboardLayerBounds
getArtboardLayerBounds(artboardId: string, 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 design.getArtboardLayerBounds('<ARTBOARD_ID>', '<LAYER_ID>')
const boundsWithEffects = layerBounds.fullBounds

Parameters:

artboardId: string

The ID of the artboard from which to inspect the layer.

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. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.

returns Promise<LayerBounds>

Various layer bounds.

Layer Lookup Methods

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

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

This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).

Example:

Layer by name from any artboard

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

Layer by function selector from any artboard

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

Layer by name from a certain artboard subset

const layer = await design.findLayer({
  name: 'Share icon',
  artboardId: [ '<ID1>', '<ID2>' ],
})

With timeout

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

Parameters:

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

A design-wide 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. newly cached artboards are not uncached). 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 artboards should be searched.

returns Promise<null | LayerFacade>

A matched layer object.

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

Returns the first layer object which has the specified ID.

Layer IDs are unique within individual artboards but different artboards can potentially have layer ID clashes. This is the reason the method is not prefixed with "get".

This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).

Example:

const layer = await design.findLayerById('<ID>')

With timeout

const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layer = await design.findLayerById('<ID>', { cancelToken: token })

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. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.

returns Promise<null | LayerFacade>

A layer object.

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

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

This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).

Example:

Layers by name from all artboards

const layers = await design.findLayers({ name: 'Share icon' })

Layers by function selector from all artboards

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

Invisible layers from all a certain artboard subset

const layers = await design.findLayers({
  visible: false,
  artboardId: [ '<ID1>', '<ID2>' ],
})

With timeout

const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layer = await design.findLayers(
  { type: 'shapeLayer' },
  { cancelToken: token }
)

Parameters:

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

A design-wide 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. newly cached artboards are not uncached). 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 artboards should be searched.

returns Promise<LayerCollectionFacade>

A layer collection with layer matches.

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

Returns a collection of all layer objects which have the specified ID.

Layer IDs are unique within individual artboards but different artboards can potentially have layer ID clashes.

This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).

Example:

const layers = await design.findLayersById('<ID>')

With timeout

const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layers = await design.findLayersById('<ID>', { cancelToken: token })

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. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.

returns Promise<LayerCollectionFacade>

A layer collection with layer matches.

getArtboardLayerAtPosition
getArtboardLayerAtPosition(artboardId: string, 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 design.getArtboardLayerAtPosition('<ARTBOARD_ID>', 100, 200)

Parameters:

artboardId: string

The ID of the artboard from which to render the layer.

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. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.

returns Promise<null | LayerFacade>

A layer object.

getArtboardLayersInArea
getArtboardLayersInArea(artboardId: string, 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:

Layers fully contained in the area

const layerIds = await design.getArtboardLayersInArea(
  '<ARTBOARD_ID>',
  { left: 80, top: 150, width: 40, height: 30 }
)

Layers fully or partially contained in the area

const layerIds = await design.getArtboardLayersInArea(
  '<ARTBOARD_ID>',
  { left: 80, top: 150, width: 40, height: 30 },
  { partialOverlap: true }
)

Parameters:

artboardId: string

The ID of the artboard from which to render the layer.

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. newly cached artboards are not uncached). 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>>

A layer list.

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

Returns a collection of all layers from all pages and artboards (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 all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).

Example:

All layers from all artboards

const layers = await design.getFlattenedLayers()

Root layers from all artboards

const rootLayers = await design.getFlattenedLayers({ depth: 1 })

With timeout

const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layers = await design.getFlattenedLayers({ cancelToken: token })

Parameters:

options: default: {}

Object

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. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.

Optionaldepth?: number

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

returns Promise<LayerCollectionFacade>

A layer collection with the flattened layers.

Asset Methods

downloadBitmapAsset
downloadBitmapAsset(bitmapAssetDesc: BitmapAssetDescriptor, options?: { cancelToken?: null | CancelToken }): Promise<string>

Downloads the specified bitmap asset to the local cache.

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

Example:

const bitmapAssetDescs = await design.getBitmapAssets({ depth: 1 })
await Promise.all(bitmapAssetDescs.map(async (bitmapAssetDesc) => {
  return design.downloadBitmapAsset(bitmapAssetDesc)
}))

Parameters:

bitmapAssetDesc: BitmapAssetDescriptor

The bitmap asset to download.

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. assets are not deleted from the disk). A cancellation token can be created via createCancelToken.

returns Promise<string>

The location of the bitmap asset within the file system.

downloadBitmapAssets
downloadBitmapAssets(bitmapAssetDescs?: Array<BitmapAssetDescriptor>, options?: { cancelToken?: null | CancelToken }): Promise<Record<string, string>>

Downloads the specified bitmap assets to the local cache.

Assets which have already been downloaded are skipped.

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

Example:

Download all assets

const bitmapAssetFilenames = await design.downloadBitmapAssets()

Download specific assets

const bitmapAssetDescs = await design.getBitmapAssets({ depth: 1 })
const bitmapAssetFilenames = await design.downloadBitmapAssets(bitmapAssetDescs)

Parameters:

bitmapAssetDescs: Array<BitmapAssetDescriptor>

A list of bitmap assets to download. When not provided, all bitmap assets of the design are downloaded.

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 asset is not deleted from the disk). A cancellation token can be created via createCancelToken.

returns Promise<Record<string, string>>

The locations of the bitmap assets within the file system. Keys of the produced object are the name values from the provided bitmap asset descriptors (or all bitmap asset names by default).

getBitmapAssetFilename
getBitmapAssetFilename(bitmapAssetDesc: BitmapAssetDescriptor, options?: { cancelToken?: null | CancelToken }): Promise<null | string>

Returns the file system location of the specified bitmap asset if it is downloaded.

The local cache has to be configured when using this method.

Example:

const bitmapAssetDescs = await design.getBitmapAssets({ depth: 1 })

const downlodedBitmapAssetFilenames = []
await Promise.all(bitmapAssetDescs.map(async (bitmapAssetDesc) => {
  const filename = design.getBitmapAssetFilename(bitmapAssetDesc)
  if (filename) {
    downlodedBitmapAssetFilenames.push(filename)
  }
}))

Parameters:

bitmapAssetDesc: BitmapAssetDescriptor

A list of bitmap assets to download.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected. A cancellation token can be created via createCancelToken.

returns Promise<null | string>

The location of the bitmap asset. null is returned when the asset is not downloaded.

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 all pages and artboards (optionally down to a specific nesting level).

This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).

Example:

All bitmap assets from all artboards

const bitmapAssetDescs = await design.getBitmapAssets()

Bitmap assets excluding pre-rendered bitmaps from all artboards

const bitmapAssetDescs = await design.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. newly cached artboards are not uncached). 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 artboards 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 in all pages and artboards (optionally down to a specific nesting level).

This method internally triggers loading of all pages and artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).

Example:

All fonts from all artboards

const fontDescs = await design.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. newly cached artboards are not uncached). 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 artboards should be searched.

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

A list of fonts.

Rendering Methods

renderArtboardLayerToFile
renderArtboardLayerToFile(artboardId: string, 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 specified 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:

await design.renderArtboardLayerToFile(
  '<ARTBOARD_ID>',
  '<LAYER_ID>',
  './rendered/layer.png'
)

With custom scale and crop and using the component background color

await design.renderArtboardLayerToFile(
  '<ARTBOARD_ID>',
  '<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:

artboardId: string

The ID of the artboard from which to render the layer.

layerId: string

The ID of the artboard layer to render.

filePath: string

The target location of the produced PNG image file.

options: default: {}

Render 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 (in the coordinate system of the artboard) 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. newly cached artboards are not uncached). 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>
renderArtboardLayersToFile
renderArtboardLayersToFile(artboardId: string, 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 specified artboard as a single composed 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 design.renderArtboardLayersToFile(
  '<ARTBOARD_ID>',
  ['<LAYER1>', '<LAYER2>'],
  './rendered/layers.png'
)

With custom scale and crop and using the custom layer configuration

await design.renderArtboardLayersToFile(
  '<ARTBOARD_ID>',
  ['<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:

artboardId: string

The ID of the artboard from which to render the layers.

layerIds: Array<string>

The IDs of the artboard layers to render.

filePath: string

The target location of the produced PNG image file.

options: default: {}

Render options

Optionalbounds?: Bounds

The area (in the coordinate system of the artboard) 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. newly cached artboards are not uncached). 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>
renderArtboardToFile
renderArtboardToFile(artboardId: string, filePath: string, options?: { bounds?: Bounds; cancelToken?: null | CancelToken; scale?: number }): Promise<void>

Renders the specified 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 design.renderArtboardToFile('<ARTBOARD_ID>', './rendered/artboard.png')

With custom scale and crop

await design.renderArtboardToFile('<ARTBOARD_ID>', './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:

artboardId: string

The ID of the artboard to render.

filePath: string

The target location of the produced PNG image file.

options: default: {}

Render options

Optionalbounds?: Bounds

The area (in the coordinate system of the artboard) to include. This can be used to either crop or expand (add empty space to) the default artboard 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. newly cached artboards are not uncached). 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>
renderPageToFile
renderPageToFile(pageId: string, filePath: string, options?: { bounds?: Bounds; cancelToken?: null | CancelToken; scale?: number }): Promise<void>

Renders all artboards from the specified page as a single PNG image file.

All visible layers from the artboards are included.

Uncached items (artboard contents 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 page area)

await design.renderPageToFile('<PAGE_ID>', './rendered/page.png')

With custom scale and crop

await design.renderPageToFile('<PAGE_ID>', './rendered/page.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 },
})

Parameters:

pageId: string

The ID of the page to render.

filePath: string

The target location of the produced PNG image file.

options: default: {}

Render options

Optionalbounds?: Bounds

The area (in the coordinate system of the page) to include. This can be used to either crop or expand (add empty space to) the default page 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. newly cached artboards are not uncached). 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

exportArtboardLayerToSvgCode
exportArtboardLayerToSvgCode(artboardId: string, 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 specified 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 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 design.exportArtboardLayerToSvgCode(
  '<ARTBOARD_ID>',
  '<LAYER_ID>'
)

With custom scale and opacity

const svg = await design.exportArtboardLayerToSvgCode(
  '<ARTBOARD_ID>',
  '<LAYER_ID>',
  {
    opacity: 0.6,
    scale: 2,
  }
)

Parameters:

artboardId: string

The ID of the artboard from which to export the layer.

layerId: string

The IDs 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. newly cached artboards are not uncached). 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.

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

Exports the specified layer from the specified artboard as an SVG file.

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 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 design.exportArtboardLayerToSvgFile(
  '<ARTBOARD_ID>',
  '<LAYER_ID>',
  './layer.svg'
)

With custom scale and opacity

await design.exportArtboardLayerToSvgFile(
  '<ARTBOARD_ID>',
  '<LAYER_ID>',
  './layer.svg',
  {
    opacity: 0.6,
    scale: 2,
  }
)

Parameters:

artboardId: string

The ID of the artboard from which to export the export.

layerId: string

The IDs of the artboard layer to export.

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. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.

Optionalscale?: number

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

returns Promise<void>
exportArtboardLayersToSvgCode
exportArtboardLayersToSvgCode(artboardId: string, 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 specified 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 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 design.exportArtboardLayersToSvgCode(
  '<ARTBOARD_ID>',
  ['<LAYER1>', '<LAYER2>']
)

With custom scale

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

Parameters:

artboardId: string

The ID of the artboard from which to export the layers.

layerIds: Array<string>

The IDs of the artboard layers to export.

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. newly cached artboards are not uncached). 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.

exportArtboardLayersToSvgFile
exportArtboardLayersToSvgFile(artboardId: string, layerIds: Array<string>, filePath: string, options?: { cancelToken?: null | CancelToken; scale?: number }): Promise<void>

Export the specified layers from the specified artboard as an SVG file.

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 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 design.exportArtboardLayersToSvgFile(
  '<ARTBOARD_ID>',
  ['<LAYER1>', '<LAYER2>'],
  './layers.svg'
)

With custom scale

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

Parameters:

artboardId: string

The ID of the artboard from which to export the layers.

layerIds: Array<string>

The IDs of the artboard layers to export.

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. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.

Optionalscale?: number

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

returns Promise<void>

Artboard Lookup Methods

findArtboard
findArtboard(selector: ArtboardSelector | (artboard: ArtboardFacade) => boolean): null | ArtboardFacade

Looks up the first artboard object matching the provided criteria.

Example:

const productArtboard = design.findArtboard({ name: /Product/i })
const productArtboard = design.findArtboard((artboard) => /Product/i.test(artboard.name))
const oneOfArtboards123 = design.findArtboard({ id: ['<ID1>', '<ID2>', '<ID3>'] })

Parameters:

selector: ArtboardSelector | (artboard: ArtboardFacade) => boolean

An artboard selector. All specified fields must be matched by the result.

returns null | ArtboardFacade

An artboard object.

findArtboards
findArtboards(selector: ArtboardSelector | (artboard: ArtboardFacade) => boolean): Array<ArtboardFacade>

Looks up all artboard objects matching the provided criteria.

Example:

const productArtboards = design.findArtboards({ name: /Product/i })
const productArtboards = design.findArtboards((artboard) => /Product/i.test(artboard.name))
const artboards123 = design.findArtboards({ id: ['<ID1>', '<ID2>', '<ID3>'] })

Parameters:

selector: ArtboardSelector | (artboard: ArtboardFacade) => boolean

An artboard selector. All specified fields must be matched by the results.

returns Array<ArtboardFacade>

An artboard list.

getArtboardByComponentId
getArtboardByComponentId(componentId: string): null | ArtboardFacade

Returns an artboard object of a specific (main/master) component. These can be used to work with the artboard contents.

Example:

const artboard = design.getArtboardByComponentId('<COMPONENT_ID>')

Parameters:

componentId: string

A component ID.

returns null | ArtboardFacade

An artboard object.

getArtboardById
getArtboardById(artboardId: string): null | ArtboardFacade

Returns a single artboard object. These can be used to work with the artboard contents.

Example:

const artboard = design.getArtboardById('<ARTBOARD_ID>')

Parameters:

artboardId: string

An artboard ID.

returns null | ArtboardFacade

An artboard object.

getArtboards
getArtboards(): Array<ArtboardFacade>

Returns a complete list of artboard object in the design. These can be used to work with artboard contents.

Example:

const artboards = design.getArtboards()
returns Array<ArtboardFacade>
getComponentArtboards
getComponentArtboards(): Array<ArtboardFacade>

Returns (main/master) component artboard objects. These can be used to work with artboard contents.

Example:

const componentArtboards = design.getComponentArtboards()
returns Array<ArtboardFacade>
getPageArtboards
getPageArtboards(pageId: string): Array<ArtboardFacade>

Returns artboard objects for a specific page (in case the design is paged). These can be used to work with artboard contents.

Example:

const pageArtboards = design.getPageArtboards('<PAGE_ID>')

Parameters:

pageId: string

A page ID.

returns Array<ArtboardFacade>

An artboard list.

Configuration Methods

setFallbackFonts
setFallbackFonts(fallbackFonts: Array<string>): void

Sets the fonts which should be used as a fallback in case the actual fonts needed for rendering text layers are not available.

The first font from this list which is available in the system is used for all text layers with missing actual fonts. If none of the fonts are available, the text layers are not rendered.

This configuration overrides/extends the global configuration set via setGlobalFallbackFonts. Fonts specified here are preferred over the global config.

Example:

design.setFallbackFonts([ 'Calibri', './custom-fonts/Carolina.otf', 'Arial' ])

Parameters:

fallbackFonts: Array<string>

An ordered list of font postscript names or font file paths.

returns void
setFontDirectory
setFontDirectory(fontDirectoryPath: string): void

Sets the directory where fonts should be looked up when rendering the design.

Fonts are matched based on their postscript names, not the file basenames.

This configuration overrides the global font directory configuration (set up via setGlobalFontDirectory) – i.e. fonts from the globally configured directory are not used for the design.

Example:

design.setFontDirectory('./custom-fonts')
design.setFontDirectory('/var/custom-fonts')

Parameters:

fontDirectoryPath: string

An absolute path to a directory or a path relative to the process working directory (process.cwd() in node.js). When null is provided, the configuration is cleared for the design.

returns void

Page Lookup Methods

findPage
findPage(selector: PageSelector | (page: PageFacade) => boolean): null | PageFacade

Looks up the first artboard object matching the provided criteria.

Example:

const mobilePage = design.findPage({ name: /mobile/i })
const mobilePage = design.findPage((page) => /mobile/i.test(page.name))
const oneOfPages123 = design.findPage({ id: ['<ID1>', '<ID2>', '<ID3>'] })

Parameters:

selector: PageSelector | (page: PageFacade) => boolean

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

returns null | PageFacade

A page object.

findPages
findPages(selector: PageSelector | (page: PageFacade) => boolean): Array<PageFacade>

Looks up all artboard objects matching the provided criteria.

Example:

const mobilePages = design.findPages({ name: /mobile/i })
const mobilePages = design.findPages((page) => /mobile/i.test(page.name))
const pages123 = design.findPages({ id: ['<ID1>', '<ID2>', '<ID3>'] })

Parameters:

selector: PageSelector | (page: PageFacade) => boolean

A page selector. All specified fields must be matched by the results.

returns Array<PageFacade>

A page list.

getPageById
getPageById(pageId: string): null | PageFacade

Returns a single page object. These can be used to work with the page contents and contents of artboards inside the page.

Example:

const page = design.getPageById('<PAGE_ID>')

Parameters:

pageId: string

A page ID.

returns null | PageFacade

A page object.

getPages
getPages(): Array<PageFacade>

Returns a complete list of page object in the design. These can be used to work with artboard contents.

An empty list is returned for unpaged designs.

Example:

const pages = design.getPages()
returns Array<PageFacade>
isPaged
isPaged(): boolean

Returns info about whether the design is paged (i.e. has artboards organized on different pages).

Example:

const shouldRenderPageList = design.isPaged()
returns boolean

Serialization Methods

exportDesignFile
exportDesignFile(filePath: string, options?: { cancelToken?: null | CancelToken }): Promise<void>

Downloads the design file of the specified format produced by a server-side design file export.

In case no such export has been done for the design yet, a new export is initiated and the resulting design file is downloaded.

Example:

Export a Figma design as a Sketch design file (the only supported conversion)

await design.exportDesignFile('./exports/design.sketch')

Parameters:

filePath: string

An absolute path to which to save the design file or a path relative to the current working directory.

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. a partially downloaded file is not deleted). A cancellation token can be created via createCancelToken.

returns Promise<void>
getExportToFormat
getExportToFormat(format: "sketch", options?: { cancelToken?: null | CancelToken }): Promise<DesignExportFacade>

Returns info about a design file of the specified format produced by a server-side design file format export.

In case no such export has been done for the design yet, a new export is initiated and the resulting design file info is then returned.

Example:

// Initiate/fetch an export of a Figma design to the Sketch format (the only supported conversion)
const export = await design.getExportToFormat('sketch')

// Optional step to get lower-level info
const url = await export.getResultUrl()
console.log('Downloading export:', url)

// Download the exported Sketch design file
await export.exportDesignFile('./exports/design.sketch')

Parameters:

format: "sketch"

The format to which the design should be exported.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected. A cancellation token can be created via createCancelToken.

returns Promise<DesignExportFacade>

A design export object.

Status Methods

destroy
destroy(): Promise<void>

Releases all loaded data of the design from memory. The design object is no longer usable after this.

If it is only desired to clean loaded data from memory while keeping the object usable, call unload instead.

returns Promise<void>
unload
unload(): Promise<void>

Releases all loaded data of the design from memory. The design object can be used for loading the data again later.

returns Promise<void>
unloadArtboard
unloadArtboard(artboardId: string): Promise<void>

Releases data related to the specified artboard from memory.

Parameters:

artboardId: string

The ID of the artboard to unload.

returns Promise<void>