Introduction

This is a prototype Javascript API for Sketch. It’s still a work in progress, but the intention is to make something which is:

• native Javascript
• an easily understandable subset of the full internals of Sketch
• fully supported by Sketch between releases (ie we try not to change it, unlike our internal API which we can and do change whenever we need to)
• still allows you to drop down to our internal API when absolutely necessary.

The idea is to keep this API as lean-and-mean as possible. The main reason for that is that if we (Sketch) are committing ourselves to making sure that we don’t break it, then it’s essential that doing so doesn’t become an unmanageable task.

Again, this is very much a work in progress, so comments and suggestions for this API are welcome - send them to developer@sketch.com, or open an issue to have a public discussion.

Installation

var sketch = require('sketch/dom')
var async = require('sketch/async')
var DataSupplier = require('sketch/data-supplier')
var UI = require('sketch/ui')
var Settings = require('sketch/settings')

// a more convenient require which exposes everything (might be a bit slower)
var sketch = require('sketch')

The API comes bundled inside Sketch, so no installation is required. You access it by calling the global require function.

Sketch Components

The approach taken by the API is to wrap the native Sketch model objects inside javascript objects. These are thin wrappers, and contain no state - they just exist as a way to provide a cleaner and more stable coding interface to the underlying model.

Each Component follows the same API:

• Component.fromNative(sketchObject) returns a wrapped object from a native Sketch model object
• Component.toJSON() return a JSON object that represent the component
• new Component(properties) creates a new native Sketch model object and returns a wrapped object
• componentInstance.sketchObject returns the native Sketch model object.
• componentInstance.isImmutable() returns true if the component is wrapping an immutable version of a native Sketch model object. If that is the case, you won’t be able to mutate the object (setting any property will be a no-op).
• componentInstance.type returns a string that represent the type of the component. If it’s undefined, it means that we couldn’t match the native object and that we returned a really lightweight wrapper.

Document

var Document = require('sketch/dom').Document

A Sketch document.

Access the selected Document

var document = require('sketch/dom').getSelectedDocument()

// also exposed on Document
var document = Document.getSelectedDocument()

Returns

The selected Document or undefined if no document is open.

Access all the open Documents

var documents = require('sketch/dom').getDocuments()

// also exposed on Document
var documents = Document.getDocuments()

Returns

An array of Documents.

Create a new Document

var document = new Document()

Open a Document

// ask the user to select a document
Document.open((err, document) => {
  if (err) {
    // oh no, we failed to open the document
  }
  // if the user cancel the opening, `document` will be `undefined`
})

// open a sketch document at the specified path
Document.open('path/to/the/document.sketch', (err, document) => {
  if (err) {
    // oh no, we failed to open the document
  }
})

A method to open an existing sketch document or ask the user to open one. The method is asynchronous so if you want to do something after the document is opening it, make sure that you pass a callback and continue your script there.

Find a Layer by Id

var layer = document.getLayerWithID(layerId)
if (layer) {
  // do something
}

A method to help find the first layer in this document which has the given id.

Returns

Return a Layer object or undefined if it’s not found.

Find Layers by name

var layers = document.getLayersNamed(name)
if (layers.length) {
  // do something
}

A method to help find the layers in this document which have the given name.

Returns

Return an array of Layer.

Find a Shared Layer Style

var sharedStyle = document.getSharedLayerStyleWithID(sharedStyleId)

A method to help find a shared style in the document.

Returns

Return a SharedStyle object or undefined if it’s not found.

Find a Shared Text Style

var sharedStyle = document.getSharedTextStyleWithID(sharedStyleId)

A method to help find a shared style in the document.

Returns

Return a SharedStyle object or undefined if it’s not found.

Get all the Symbol Sources

var symbols = document.getSymbols()

A method to get all Symbol Sources defined in the document.

Returns

Return an array of the SymbolMaster objects defined in the document.

Find a Symbol Source

var source = document.getSymbolMasterWithID(symbolInstance.symbolId)

A method to help find a Symbol Source in the document.

Returns

Return a SymbolMaster object or undefined if it’s not found.

Center on Layer

document.centerOnLayer(layer)

A method to help center the view of the document window on a given layer.

Save the Document

document.save()

document.save('path/to/the/document.sketch')

document.save('path/to/the/document.sketch', (err) => {
  if (err) {
    // saving the document failed :(
  }
})

A method to save a document to a specific path or ask the user to choose where to save it. The method is asynchronous so if you want to do something after the document is saved, make sure that you pass a callback and continue your script there.

Close the Document

document.close()

A method to close a document.

Change the color space

// By default the method assigns a new color space
document.changeColorSpace(ColorSpace.sRGB)
console.log(document.colorSpace === ColorSpace.sRGB) // true

// Pass true as an optional second argument
// to convert instead of assign
document.changeColorSpace(ColorSpace.P3, true)
console.log(document.colorSpace === ColorSpace.P3) // true

// Alternatively, use the property setter (the behaviour
// here is to always assign the color space)
document.colorSpace = ColorSpace.P3
console.log(document.colorSpace === ColorSpace.P3) // true

// Create a document with a pre-defined color space
const p3Doc = new Document({ colorSpace: ColorSpace.P3 })

A method to change a document’s color space. For an in-depth discussion of this topic and the difference between assigning and converting the color space check the color management documentation.

Document.SaveMode

Document.SaveMode.SaveAs

document.save('path/to/the/document.sketch', {
  saveMode: Document.SaveMode.SaveAs,
})

Enumeration of the save mode.

Document.ColorSpace

Document.ColorSpace.Unmanaged
Document.ColorSpace.sRGB
Document.ColorSpace.P3

Enumeration of the available color space settings.

Library

var Library = require('sketch/dom').Library

A Sketch Library.

Access all the Libraries

var libraries = require('sketch/dom').getLibraries()

// also exposed on Library
var libraries = Library.getLibraries()

Returns

An array of Libraries.

Get a Library from a path

var library = Library.getLibraryForDocumentAtPath(
  'path/to/existing/document.sketch'
)

Get the library for a local Sketch document. If the Document was already added as a Library, it will simply return it. If it is not already a Library, it will be added.

Returns

The existing Library at the path or a new Library from the document at the path.

Get a remote Library from an RSS feed URL

Library.getRemoteLibraryWithRSS(
  'https://url/to/feed/rss.xml',
  (err, library) => {
    if (err) {
      // oh no, failed to load the library
    }
  }
)

Get the remote library for an RSS feed. If the RSS feed was already added as a Library, it will simply return it. If it is not already a Library, it will be added.

Remove a Library

library.remove()

A method to remove an existing library.

Get the Library’s Document

var libDocument = library.getDocument()

A library references a Sketch Document and you can access it with this method.

Returns

The Document that the Library references. It can throw an error if the Document cannot be accessed.

Get the Symbols that can be imported

var document = sketch.getSelectedDocument()
var symbolReferences = library.getImportableSymbolReferencesForDocument(
  document
)

To import a Symbol from a Library, do not access its Document and look for the Symbol Source directly. Instead, get the Symbol References of the Library and use those to import them.

Those references depends on the document you want to import them into. For example if a document has already imported a symbol, it will reference the local version to keep all the instances in sync.

Returns

An array of Shareable Object that represents the Symbols which you can import from the Library.

Get the Shared Layer Styles that can be imported

var document = sketch.getSelectedDocument()
var stylesReferences = library.getImportableLayerStyleReferencesForDocument(
  document
)

To import a shared style from a Library, do not access its Document and look for the SharedStyle directly. Instead, get the Shared Layer Style References of the Library and use those to import them.

Those references depends on the document you want to import them into. For example if a document has already imported a shared style, it will reference the local version to keep all the instances in sync.

Returns

An array of Shareable Object that represents the Shared Layer Styles which you can import from the Library.

Get the Shared Text Styles that can be imported

var document = sketch.getSelectedDocument()
var stylesReferences = library.getImportableTextStyleReferencesForDocument(
  document
)

To import a shared style from a Library, do not access its Document and look for the SharedStyle directly. Instead, get the Shared Text Style References of the Library and use those to import them.

Those references depends on the document you want to import them into. For example if a document has already imported a shared style, it will reference the local version to keep all the instances in sync.

Returns

An array of Shareable Object that represents the Shared Layer Styles which you can import from the Library.

Get the Shared Swatches that can be imported

var document = sketch.getSelectedDocument()
var stylesReferences = library.getImportableSwatchReferencesForDocument(
  document
)

To import a Swatch from a Library, do not access its Document and look for the Swatch directly. Instead, get the Shared Swatch References of the Library and use those to import them.

Those references depends on the document you want to import them into. For example if a document has already imported a shared Swatch, it will reference the local version to keep all the instances in sync.

Returns

An array of Shareable Object that represents the Shared Swatches which you can import from the Library.

Library.LibraryType

Library.LibraryType.LocalUser

Enumeration of the types of Library.

Importable Object

var symbolReferences = library.getImportableSymbolReferencesForDocument(
  document
)

An Object that can be imported from a Library. All its properties are read-only.

Import in the Document

var symbol = symbolReference.import()
var style = sharedStyleReference.import()

An Importable Object is linked to a Document so importing it will import it in the said Document.

Returns

If the objectType of the Object is Symbol, it will return a Symbol Source which will be linked to the Library (meaning that if the Library is updated, the Symbol Instances created from the Source will be updated as well).

Library.ImportableObjectType

Library.ImportableObjectType.Symbol

Enumeration of the types of Importable Objects.

Style

var Style = require('sketch/dom').Style

var shape = new Shape({
  style: {
    borders: [{ color: '#c0ffee' }],
  },
})

shape.style.fills = [
  {
    color: '#c0ffee',
    fillType: Style.FillType.Color,
  },
]

text.style.textUnderline = 'double dash-dot'

The style of a Layer.

Get the default line height

var defaultlineHeight = style.getDefaultLineHeight()

When no line height is specified, style.lineHeight will be undefined. You can get the default line height of the font using style.getDefaultLineHeight().

Returns

A number if the layer is a Text layer or undefined.

Check if the Style is in sync with a Shared Style

var isOutOfSync = style.isOutOfSyncWithSharedStyle(sharedStyle)

Returns

Whether the Style has some differences with a Shared Style.

Sync the Style with a Shared Style

style.syncWithSharedStyle(sharedStyle)

The style instance will be updated with the value of the Shared Style.

var sharedStyle = styledLayer.sharedStyle
sharedStyle.style = style

The Shared Style value will be updated with the style.

Style.BlendingMode

Style.BlendingMode.Darken

Enumeration of the blending mode.

Blur

shape.style.blur = {
  center: {
    x: 10,
    y: 20,
  },
  type: Style.BlurType.Motion,
  motionAngle: 10,
}

An object that represent the blur of the layer.

Style.BlurType

Style.BlurType.Background

Enumeration of the type of a blur.

Fill

shape.style.fills = [
  {
    color: '#c0ffee',
    fillType: Style.FillType.Color,
  },
]

An object that represent a Fill. color, gradient and pattern will always be defined regardless of the type of the fill.

Style.FillType

Style.FillType.Color

Enumeration of the types of fill.

Style.PatternFillType

Style.PatternFillType.Fit

Enumeration of the types of pattern fill.

Border

shape.style.borders = [
  {
    color: '#c0ffee',
    fillType: Style.FillType.Color,
    position: Style.BorderPosition.Inside,
  },
]

An object that represent a Border.

Style.BorderPosition

Style.BorderPosition.Center

Enumeration of the positions of a border.

BorderOptions

shape.style.borderOptions = {
  dashPattern: [20, 5, 20, 5],
}

An object that represent the options that the Borders of the Layer share.

Style.Arrowhead

Style.Arrowhead.OpenArrow

Enumeration of the type of the Arrowhead for line layers.

Style.LineEnd

Style.LineEnd.Round

Enumeration of the positions of a border.

Style.LineJoin

Style.LineJoin.Miter

Enumeration of the positions of a border.

Shadow

shape.style.shadows = [
  {
    color: '#c0ffee',
    blur: 3,
  },
]

shape.style.innerShadows = [
  {
    color: '#c0ffee',
    blur: 3,
  },
]

An object that represent a Shadow.

Gradient

shape.style.fills = [
  {
    fillType: Style.FillType.Gradient,
    gradient: {
      gradientType: Style.GradientType.Linear,
      from: {
        x: 0,
        y: 0,
      },
      to: {
        x: 50,
        y: 50,
      },
      stops: [
        {
          position: 0,
          color: '#c0ffee',
        },
        {
          position: 0.5,
          color: '#0ff1ce',
        },
        {
          position: 1,
          color: '#bada55',
        },
      ],
    },
  },
]

An object that represent a Gradient.

Style.GradientType

Style.GradientType.Radial

Enumeration of the type of a Gradient.

Gradient Stops

An object that represent a Gradient Stop. Each of colors of a Gradient are represented by a Stop. A Gradient can have as many Stops as you’d like.

Font Axes

// Get the axes
const axes = textLayer.style.fontAxes

// If axes is non-null the Text Layer's font
// is a valid variable font recognised by Sketch
if (axes) {
  // Mutate the axes object, taking care
  // to work within the min and max range
  // specified for each axis
  axes.Weight.value = axes.Weight.max
  axes.Monospace.value = 1
  // Apply the new axes to update
  // the text layer
  textLayer.style.fontAxes = axes
}

The fontAxes property allows you to adjust the parameters, or “axes”, exposed by variable fonts.

It works by allowing you to get and set an object representing the axes for a Text Layer’s current font. The object will only contain information about the axes supported by the Text Layer’s current font, and these will vary from font to font.

The object is keyed by axis name, and has values with the following structure:

Shared Style

var SharedStyle = require('sketch/dom').SharedStyle

document.sharedTextStyles.push({
  name: 'Header 1',
  style: text.style,
})

A shared style (either a layer style or a text style).

Note that the id of a Shared Style coming from a Library might look like this: FBFF821E-20F3-48C5-AEDC-89F97A8C2344[D1A683E0-5333-4EBE-977C-48F64F934E99].

If you have a Symbol Instance which has a Layer using a Shared Style from a Library and a Layer in the Document using the same Shared Style from the Library, the style will be imported twice; once for use in the layer and once for use by the foreign Symbol. The reason for this is to do with syncing. If you change the Shared Style in the Library it will cause both the Symbol Instance and the Shared Style to be out-of-date in the document. This will be shown in the component sync sheet, but you can choose only to sync the Shared Style (or the Symbol). Using these “private” Shared Styles means that syncing just the shared style doesn’t implicitly also sync the symbol.

The format of these Symbol private shared style IDs is SYMBOLID[STYLEID] Where: STYLEID is the id of the original Shared Style in the original Library. And SYMBOLID is the new symbolId of the foreign Symbol in the destination document.

Where we have such as Symbol private style, the same ID will be used both as the local ID and as the remote ID.

Create a new Shared Style from a Style

const newSharedStyle = SharedStyle.fromStyle({
  name: 'Header 1',
  style: layer.style,
  document: document,
})

// you can also push to the shared styles arrays directly
document.sharedTextStyles.push({
  name: 'Header 1',
  style: text.style,
})

Create a new Shared Style with a specific name in a specific Document.

⚠️You can only insert local shared styles (eg. not linked to a Library). document.sharedLayerStyles returns the foreign shared styles (eg. linked to a Library) concatenated with the local shared styles. So if you try to insert a new Shared Style at the beginning (using unshift for example), it will end up at the beginning of the local Shared Styles but that might not be the beginning of all the shared styles if there are some foreign.

Get all the Instances

var styles = sharedStyle.getAllInstances()

Returns an array of all instances of the Shared Style in the document, on all pages.

Returns

A Style array.

Get all the Instances’ Layers

var layers = sharedStyle.getAllInstancesLayers()

Returns an array of all layers with a Style which is an instance of the Shared Style in the document, on all pages.

Returns

A Layer array.

Get Library defining the style

var originLibrary = sharedStyle.getLibrary()

If the SharedStyle was imported from a library, the method can be used to:

• know about it
• get the library back

Returns

The Library the Shared Style was defined in, or null if it is a local shared style.

Sync the local reference with the library version

const success = sharedStyle.syncWithLibrary()

If a Library has some updates, you can synchronize the local Shared Style with the Library’s version and bypass the panel where the user chooses the updates to bring.

Returns

true if it succeeded.

Unlink the local reference from the library

const success = sharedStyle.unlinkFromLibrary()

You can unlink a Shared Style from the Library it comes from and make it a local Shared Style instead.

Returns

true if it succeeded.

SharedStyle.StyleType

SharedStyle.StyleType.Text

Enumeration of the type of Shared Style. Unknown indicates the object is broken and Sketch can’t determine the style type.

Symbol Override

var overrides = symbolInstance.overrides

A Symbol override. This component is not exposed, it is only returned when accessing the overrides of a Symbol Instance or Symbol Source. The overrides are not available until after the instance is injected into the document.

Get the frame of an Override

var frame = override.getFrame()

The frame of an override can be different than the frame of its affected Layer in case where the Symbol Instance has been scaled for example.

Returns

A Rectangle describing the frame of the affected layer in the Symbol Instance’s coordinates.

Flow

var Flow = require('sketch/dom').Flow

The prototyping action associated with a layer.

Create a new prototyping action

layer.flow = {
  target: artboard,
}

You can create an action without specifying an animation type, it will use the default one.

layer.flow = {
  targetId: artboard.id,
}

You can create an action by using the ID of an Artboard instead of the artboard.

layer.flow = {
  target: artboard,
  animationType: Flow.AnimationType.slideFromLeft,
}

You can also specify the animation type.

layer.flow = {
  target: Flow.BackTarget,
}

You can also create a back action.

Check if the action is a Back action

layer.flow.isBackAction()

Returns whether the prototyping action is a back action or not, eg. whether layer.flow.target === Flow.BackTarget.

Check if the target is valid

layer.flow.isValidConnection()

In some cases, the target of the action can be invalid, for example when the target has been removed from the document. The methods returns whether the target is valid or not.

Flow.BackTarget

layer.flow = {
  target: Flow.BackTarget,
}

Flow.BackTarget is a constant that you can set the target to in order to always take you back to the last Artboard you were looking at. When a Target has been set to Flow.BackTarget, the transition leading into it will be reversed on return.

Flow.AnimationType

Flow.AnimationType.slideFromLeft

Enumeration of the animation types.

Export Format

An export format associated with a layer.

Valid export file formats

• jpg
• png
• tiff
• eps
• pdf
• webp
• svg

Selection

var selection = document.selectedLayers

A utility class to represent the layers selection. Contains some methods to make interacting with a selection easier.

map, forEach, and reduce

selection.forEach(layer => log(layer.id))

selection.map(layer => layer.id)

selection.reduce((initial, layer) => {
  initial += layer.name
  return initial
}, '')

Even though a selection isn’t an array, it defines map, forEach and reduce by just forwarding the arguments to its layers. Those are just convenience methods to avoid getting the layers every time.

Clear the Selection

selection.clear()

Clears the selection.

Returns

Return the selection (useful if you want to chain the calls).

Point

A utility class to represent a point.

Get a CGPoint

var cgPoint = point.asCGPoint()

Return the Point as a CGPoint.

Get an NSPoint

var nsPoint = rect.asNSPoint()

Return the Point as a NSPoint.

CurvePoint

A utility class to represent a curve point (with handles to control the curve in a path).

Check if the point is selected

shape.points[0].isSelected()

In case the user is currently editing a path, you can check if a curve point is selected using the curvePoint.isSelected() method.

CurvePoint.PointType

Enumeration of the animation types.

Rectangle

var Rectangle = require('sketch/dom').Rectangle

var rect = new Rectangle(0, 0, 100, 100)

var rectFromAnotherRect = new Rectangle(rect)

A utility class to represent a rectangle. Contains some methods to make interacting with a rectangle easier.

Offset the Rectangle

var newRect = rect.offset(x, y)

Adjust the rectangle by offsetting it.

Returns

Return this rectangle (useful if you want to chain the calls).

Scale the Rectangle

var newRect = rect.scale(scaleWidth, scaleHeight)

Adjust the rectangle by scaling it. The scaleHeight argument can be omitted to apply the same factor on both the width and the height.

Returns

Return this rectangle (useful if you want to chain the calls).

Change the coordinates basis

var newRect = rect.changeBasis({
  from: layerA,
  to: layerB,
})

var parentRect = rect.changeBasis({
  from: layerA,
  to: layerA.parent,
})

var pageRect = rect.changeBasis({
  from: layerA,
  // leaving out `to` means changing the
  // basis to the Page's basis
})

Each layer defines its own system of coordinates (with its origin at the top left of the layer). You can change that basis from one layer to the other with changeBasis.

Both from and to can be omitted (but not at the same time) to change the basis from/to the Page coordinates.

Get a CGRect

var cgRect = rect.asCGRect()

Return the Rectangle as a CGRect.

Get an NSRect

var nsRect = rect.asNSRect()

Return the Rectangle as a NSRect.

fromNative

var sketch = require('sketch/dom')
var document = sketch.fromNative(context.document)

A utility function to get a wrapped object from a native Sketch model object.

Returns

The wrapped object of the right type (you can check is type with wrappedObject.type), eg. a native document will be wrapped as a Document while a native text layer will be wrapped as a Text.

Assets

Wrapper classes that are used to represent reusable assets retrieved from a document or globally.

Color Asset

Get the Global Colors

var sketch = require('sketch/dom')
var colors = sketch.globalAssets.colors

Returns

An array of ColorAsset objects.

Gradient Asset

Get the Global Gradients

var sketch = require('sketch/dom')
var gradients = sketch.globalAssets.gradients

Returns

An array of GradientAsset objects.

Swatch

Get a referencing Color

var sketch = require('sketch')
var mySwatch = sketch.Swatch.from({
  name: 'Safety Orange',
  color: '#ff6600'
})
var myColor = mySwatch.referencingColor

Returns

A Color that references a Color Variable, which you can use anywhere the API expects a Color object.

SmartLayout

The SmartLayout object contains the set of possible Smart Layouts that can be applied to SymbolMaster and Group layers.

Set a Smart Layout

const SmartLayout = require('sketch').SmartLayout
layer.smartLayout = SmartLayout.TopToBottom

Given a reference to a SymbolMaster or Group layer use the smartLayout setter to apply one of the Smart Layout values.

Clear a Smart Layout

Set the smartLayout value to null to remove the Smart Layout. This is the equivalent of selecting “None” in the Sketch Inspector.

symbol.smartLayout = null

Trigger a smart layout

const SmartLayout = require('sketch').SmartLayout
symbol.smartLayout = SmartLayout.TopToBottom
symbolInstance.resizeWithSmartLayout()

In order to trigger a Smart Layout resize in an instance, for example after changing an override value, call the resizeWithSmartLayout() method on the SymbolInstance layer.

Layer

A Sketch layer. This is the base class for most of the Sketch components and defines methods to manipulate them.

Duplicate the Layer

var duplicatedLayer = layer.duplicate()

A new identical layer will be inserted into the parent of this layer.

Returns

A new Layer.

Remove the Layer

layer.remove()

Remove this layer from its parent.

Returns

The current layer (useful if you want to chain the calls).

Get the position in the hierarchy

var index = layer.index

The index of this layer in its parent. The layer at the back of the parent (visually) will be layer 0. The layer at the front will be layer n - 1 (if there are n layers).

Move the Layer in the hierarchy

Using the index

layer.index = 2

You can set the index of the layer to move it in the hierarchy.

Move to the front

layer.moveToFront()

// which is the same as

layer.index = layer.parent.layers.length - 1

Move this layer to the front of its parent.

Returns

The current layer (useful if you want to chain the calls).

Move forward

layer.moveForward()

// which is the same as

layer.index = layer.index + 1

Move this layer forward in its parent.

Returns

The current layer (useful if you want to chain the calls).

Move to the back

layer.moveToBack()

// which is the same as

layer.index = 0

Move this layer to the back of its parent.

Returns

The current layer (useful if you want to chain the calls).

Move backward

layer.moveBackward()

// which is the same as

layer.index = layer.index - 1

Move this layer backward in its parent.

Returns

The current layer (useful if you want to chain the calls).

Accessing the layer’s hierarchy

// access the page the layer is in
layer.getParentPage()
page.getParentPage() === undefined

// access the artboard the layer is in (if any)
layer.getParentArtboard()
artboard.getParentArtboard() === undefined

// access the Symbol Source the layer is in (if any)
layer.getParentSymbolMaster()
symbolMaster.getParentSymbolMaster() === undefined

// access the shape the layer is in (if any)
layer.getParentShape()

In addition to the direct parent, you can access a few other entities in the hierarchy of the layer.

Group

var Group = require('sketch/dom').Group

A group of layers. It is also an instance of Layer so all the methods defined there are available.

Create a new Group

new Group()

var group = new Group({
  name: 'my name',
  layers: [
    {
      type: sketch.Types.Text,
      text: 'Hello world',
    },
  ],
})

Adjust to fit its children

group.adjustToFit()

Adjust the group to fit its children.

Returns

The current group (useful if you want to chain the calls).

Page

var Page = require('sketch/dom').Page

A Sketch page. It is an instance of both Layer and Group so all the methods defined there are available.

Create a new Page

new Page()

new Page({
  name: 'my page',
})

Get the selected Layers of the Page

var selection = document.selectedLayers

A read-only property to get the layers that the user has selected in the page.

Returns

Return a Selection object.

Symbols Page

The “Symbols” page is similar to other pages. The only way it is specific is when creating a Symbol, Sketch will ask the user if they want to move it to that page.

You can put Symbols in any page but if you want to respect the convention Sketch put in place, here are a few methods to help you do so.

Get the Symbols Page

var symbolsPage = Page.getSymbolsPage(document)

A method to get the Symbols Page of a Document.

Returns

Return a Page or undefined if there is no Symbols Page yet.

Create the Symbols Page

var symbolsPage = Page.createSymbolsPage()
symbolsPage.parent = document

A method to create the Page with the name that Sketch will recognize as the Symbols Page.

Returns

Return a Page.

Knows if a Page is the Symbols Page

var isSymbolsPage = page.isSymbolsPage()

A method to tell if the page is the Symbols Page.

Returns

Return a boolean.

Artboard

var Artboard = require('sketch/dom').Artboard

A Sketch artboard. It is an instance of both Layer and Group so all the methods defined there are available.

Create a new Artboard

new Artboard()

new Artboard({
  name: 'my name',
  flowStartPoint: true,
})

Shape

var Shape = require('sketch/dom').Shape

A shape layer. It is an instance of Layer so all the methods defined there are available. It is shaped by its layers which have boolean operations between them.

Create a new Shape

new Shape({
  name: 'my shape',
})

Image

var Image = require('sketch/dom').Image

An image layer. It is an instance of Layer so all the methods defined there are available.

Create a new Image

var imageLayer = new Image({
  image: 'path/to/image.png',
})

The image property accepts a wide range of input:

• an ImageData
• a Buffer
• a native NSImage
• a native NSURL
• a native MSImageData
• a string: path to the file to load the image from
• an object with a path property: path to the file to load the image from
• an object with a base64 string: a base64 encoded image

var imageLayer = new Image({
  image: 'path/to/image.png',
  frame: new Rectangle(0, 0, 300, 200),
})

By default, an Image layer will be created with a size of 100 × 100 pixels, unless you provide a frame property on its constructor.

Original Size

imageLayer.resizeToOriginalSize()

Adjust the Image to its original size. This is equivalent to pressing the ‘Original Size’ button in Sketch’s Inspector.

Returns

The current Image (useful if you want to chain the calls).

For performance reasons, Sketch initializes the Image object lazily. So if you want to set the dimensions of your Image layer to those of the original file, you’ll first need to create the object, and then call the resizeToOriginalSize method.

ImageData

var imageData = imageLayer.image

imageData.nsimage // return a native NSImage
imageData.nsdata // return a native NSData representation of the image

An ImageData is a wrapper around a native NSImage.

You can access the native NSImage with nsimage or a native NSData representation of the image with nsdata.

imageLayer.image.size // { width: 100, height: 100 }

As a convenience, you can access the original size of an ImageData object via its size property.

ShapePath

var ShapePath = require('sketch/dom').ShapePath

A shape path layer. It is an instance of Layer so all the methods defined there are available.

Create a new ShapePath

const shapePath = new ShapePath({
  name: 'my shape path',
  shapeType: ShapePath.ShapeType.Oval,
})

You can only set the shapeType when creating a new one. Once it is created, the shapeType is read-only. If it is not specified and you do not specify any points, it will default to ShapePath.ShapeType.Rectangle (if you do specify some points, it will default to ShapePath.ShapeType.Custom).

const shapePath = ShapePath.fromSVGPath('M10 10 H 90 V 90 H 10 L 10 10')

You can also create a new ShapePath from an SVG path (the string that goes in the d attribute of a path tag in an SVG). See the MDN documentation for more information about SVG paths.

Get the SVG path

const svgPath = shapePath.getSVGPath()

Returns a string representing the SVG path of the ShapePath.

ShapePath.ShapeType

ShapePath.ShapeType.Oval

Enumeration of the type of Shared Style.

ShapePath.PointType

ShapePath.PointType.Undefined

Enumeration of the point types.

Text

var Text = require('sketch/dom').Text

A text layer. It is an instance of Layer so all the methods defined there are available.

Create a new Text

var text = new Text({
  text: 'my text',
  alignment: Text.Alignment.center,
})

Adjust to fit its value

text.adjustToFit()

Adjust the Text to fit its value.

Returns

The current Text (useful if you want to chain the calls).

fragments

var fragments = text.fragments

Returns a array of the text fragments for the text. Each one is a object containing a rectangle, a baseline offset, the range of the fragment, and the substring {rect, baselineOffset, range, text}.

Text.Alignment

Text.Alignment.center

Enumeration of the alignments of the text.

Text.VerticalAlignment

Text.VerticalAlignment.center

Enumeration of the vertical alignments of the text.

Text.LineSpacing

Text.LineSpacing.constantBaseline

Enumeration of the line spacing behavior for the text.

Symbol Source

var SymbolMaster = require('sketch/dom').SymbolMaster

A Symbol Source. It is an instance of Artboard (hence of Layer and Group) so all the methods defined there are available.

Create a new Symbol Source

var symbol = new SymbolMaster({
  name: 'my symbol',
})

Create a new Symbol Source from an Artboard

var symbol = SymbolMaster.fromArtboard(artboard)

Replace the artboard with a Symbol Source.

Returns

A new SymbolMaster

Change to an Artboard

var artboard = symbol.toArtboard()

Replace the Symbol Source with an artboard and detach all its instances converting them into groups.

Returns

A new Artboard

Create a new Instance

var instance = symbol.createNewInstance()

Creates a new SymbolInstance linked to this Source, ready for inserting in the document.

Returns

A new SymbolInstance

Get all the Instances

var instances = symbol.getAllInstances()

Returns an array of all instances of the Symbol in the document, on all pages.

Get Library defining the Symbol Source

var originLibrary = symbol.getLibrary()

If the Symbol Source was imported from a library, the method can be used to:

• know about it
• get the library back

Returns

The Library the Symbol was defined in, or null if it is a local symbol.

Sync the local reference with the library version

const success = symbol.syncWithLibrary()

If a Library has some updates, you can synchronize the local Symbol Source with the Library’s version and bypass the panel where the user chooses the updates to bring.

Returns

true if it succeeded.

Unlink the local reference from the library

const success = symbol.unlinkFromLibrary()

You can unlink a Symbol Source from the Library it comes from and make it a local Symbol Source instead. It will be added to the Symbols Page.

Returns

true if it succeeded.

Symbol Instance

var SymbolInstance = require('sketch/dom').SymbolInstance

A Symbol instance. It is an instance of Layer so all the methods defined there are available.

Create a new Symbol Instance

var instance = new SymbolInstance({
  name: 'my symbol instance',
  symbolId: symbolId,
})

Create a new Symbol Instance from a Symbol Source

var instance = symbol.createNewInstance()

Creates a new SymbolInstance linked to this Source, ready for inserting in the document.

Returns

A new SymbolInstance

Detach the instance

var group = instance.detach()

var group = instance.detach({
  recursively: true,
})

Replaces a group that contains a copy of the Symbol this instance refers to. Returns null if the Source contains no layers instead of inserting an empty group

Returns

A new Group or null

Set an Override value

instance.setOverrideValue(instance.overrides[0], 'overridden')

Change the value of the override.

Returns

The current Symbol instance (useful if you want to chain the calls).

Resize with Smart Layout

instance.resizeWithSmartLayout()

In order to trigger a Smart Layout resize in an instance, for example after changing an override value, call the resizeWithSmartLayout() method.

HotSpot

var HotSpot = require('sketch/dom').HotSpot

A Sketch hotspot. It is an instance of Layer so all the methods defined there are available.

Create a new Hotspot

new HotSpot()

new HotSpot({
  name: 'my name',
  flow: {
    target: artboard,
  },
})

Create a new Hotspot from a Layer

var hotspot = HotSpot.fromLayer(layer)

Slice

var Slice = require('sketch/dom').Slice

A Sketch slice. It is an instance of Layer so all the methods defined there are available.

Settings

var Settings = require('sketch/settings')

A set of functions to handle user settings. The settings are persisted when the user closes Sketch.

Get a plugin setting

var setting = Settings.settingForKey('my-key')

Return the value of a setting scoped to your plugin for a given key.

Returns

The setting that was stored for the given key. undefined if there was nothing.

Set a plugin setting

Settings.setSettingForKey('my-key', 0.1)

Store a value of a setting scoped to your plugin for a given key.

Get a Sketch setting

var setting = Settings.globalSettingForKey('my-key')

Return the value of a Sketch setting for a given key.

Returns

The setting that was stored for the given key. undefined if there was nothing.

Set a Sketch setting

Settings.setGlobalSettingForKey('my-key', 0.1)

Store a value of a Sketch setting for a given key.

Get a Layer setting

var setting = Settings.layerSettingForKey(layer, 'my-key')

Return the value of a setting for a given key on a specific Layer or DataOverride or Override.

Returns

The setting that was stored for the given key. undefined if there was nothing.

Set a Layer setting

Settings.setLayerSettingForKey(layer, 'my-key', 0.1)

Store a value of a setting for a given key on a specific Layer or DataOverride or Override.

Get a Document setting

var setting = Settings.documentSettingForKey(document, 'my-key')

Return the value of a setting for a given key on a specific document.

Returns

The setting that was stored for the given key. undefined if there was nothing.

Set a Document setting

Settings.setDocumentSettingForKey(document, 'my-key', 0.1)

Store a value of a setting for a given key on a specific document.

Get a session variable

var myVar = Settings.sessionVariable('myVar')

Return the value of a variable which is persisted when the plugin finishes to run but is not persisted when Sketch closes. It is useful when you want to keep a value between plugin’s runs.

Returns

The setting that was stored for the given key. undefined if there was nothing.

Set a session variable

Settings.setSessionVariable('myVar', 0.1)

Store a value of a variable which is persisted when the plugin finishes to run but is not persisted when Sketch closes. It is useful when you want to keep a value between plugin’s runs.

UI

var UI = require('sketch/ui')

A set of functions to show some user interfaces. The set is small on purpose. Any more complex UI should be provided by third party libraries and doesn’t need to be in the core.

Show a message

UI.message('Hello world!')

Show a small, temporary, message to the user. The message appears at the bottom of the selected document, and is visible for a short period of time. It should consist of a single line of text.

Show an alert

UI.alert('my title', 'Hello World!')

Show an alert with a custom title and message. The alert is modal, so it will stay around until the user dismisses it by pressing the OK button.

Get an input from the user

UI.getInputFromUser(
  "What's your name?",
  {
    initialValue: 'Appleseed',
  },
  (err, value) => {
    if (err) {
      // most likely the user canceled the input
      return
    }
  }
)

UI.getInputFromUser(
  "What's your favorite design tool?",
  {
    type: UI.INPUT_TYPE.selection,
    possibleValues: ['Sketch', 'Paper'],
  },
  (err, value) => {
    if (err) {
      // most likely the user canceled the input
      return
    }
  }
)

Shows a simple input sheet which displays a message, and asks for an input from the user.

UI.INPUT_TYPE

UI.INPUT_TYPE.selection

The enumeration of the different input types.

Get the theme of Sketch

var theme = UI.getTheme()

if (theme === 'dark') {
  // shows UI in dark theme
} else {
  // shows UI in light theme
}

Sketch has 2 themes: light and dark. If your plugin has some custom UI, it should support both as well.

Data Supplier

var DataSupplier = require('sketch/data-supplier')

When your plugin supplies some data, don’t forget to set the suppliesData field to true in your manifest.json!

Register a Data Supplier

var DataSupplier = require('sketch/data-supplier')

// onStartup would be the handler for the `Startup` action defined in the manifest.json
export function onStartup() {
  DataSupplier.registerDataSupplier(
    'public.text',
    'My Custom Data',
    'SupplyKey'
  )
}

Register some data with a name and a key.

Context of the action

When a user runs a Data plugin, Sketch will forward the request to your plugin, passing a context.data object with all the information you need to fulfil the request:

var util = require('util')
var sketch = require('sketch/dom')
var DataSupplier = require('sketch/data-supplier')

// onSupplyKeyNeeded would be the handler for
// the `SupplyKey` action defined in the manifest.json
export function onSupplyKeyNeeded(context) {
  var count = context.data.items.count()
  var key = context.data.key
  var items = context.data.items

  // you will often want to get wrapped objects instead
  // of the native ones supplied in the context
  var wrappedItems = util.toArray(items).map(sketch.fromNative)
}

Supply the Data

You have two different methods to supply data from your plugin: supplyData (to provide all the data at once), and supplyDataAtIndex (to provide data one by one).

Supply all the data in one go

var DataSupplier = require('sketch/data-supplier')

// onSupplyKeyNeeded would be the handler for
// the `SupplyKey` action defined in the manifest.json
export function onSupplyKeyNeeded(context) {
  var count = context.data.items.count()
  var key = context.data.key

  var data = Array.from(Array(count)).map(i => 'foo')

  DataSupplier.supplyData(key, data)
}

When the plugin providing the dynamic data has finished generating the data (could be an asynchronous operation), it will call this function with the data key and the data.

Supply the data one by one

var util = require('util')
var sketch = require('sketch/dom')
var DataSupplier = require('sketch/data-supplier')

// onSupplyKeyNeeded would be the handler for
// the `SupplyKey` action defined in the manifest.json
export function onSupplyKeyNeeded(context) {
  var key = context.data.key
  var items = util.toArray(context.data.items).map(sketch.fromNative)

  items.forEach((item, i) => {
    // item is either a Layer or a DataOverride
    DataSupplier.supplyDataAtIndex(key, 'foo', i)
  })
}

When the plugin providing the dynamic data has finished generating the datum (could be an asynchronous operation), it will call this function with the data key and the datum.

DataOverride

A special object passed in the context of the action to supply data when the item is an Override.

Deregister your Data Suppliers

var DataSupplier = require('sketch/data-supplier')

// onShutdown would be the handler for the `Shutdown` action defined in the manifest.json
export function onShutdown() {
  DataSupplier.deregisterDataSuppliers()
}

When registering something, it’s good practice to clean up after it. This is specially useful when your plugin is updated: the Shutdown Action will be called before the Startup will. It gives you the opportunity to update your handler cleanly.

async

var fiber = require('sketch/async').createFiber()
longRunningTask(function(err, result) {
  fiber.cleanup()
  // you can continue working synchronously here
})

By default, Sketch cleans up your script as soon as its call-stack is empty. So if you schedule an asynchronous task, chances are that when the task returns, your script will be cleaned up and it will crash Sketch.

A fiber is a way to keep track of a asynchronous task. The script will stay alive as long as at least one fiber is running.

To end a fiber, call fiber.cleanup(). This will tell Sketch that it can garbage collect the script if no other fiber is running.

You can run a function when the fiber is about to be cleaned up by setting a callback: fiber.onCleanup(function () {...}). Always do your clean up in this function instead of doing before calling fiber.cleanup: there might be some cases where the fiber will be cleaned up by Sketch so you need to account for that.

export

var sketch = require('sketch/dom')
sketch.export(layer, {
  formats: 'svg',
})

sketch.export([layer, layer2])

const options = { scales: '1, 2, 3', formats: 'png, jpg' }
sketch.export(page, options)

sketch.export(document.pages)

const options = { formats: 'json', output: false }
const sketchJSON = sketch.export(layer, options)

const options = { formats: 'png', output: false }
const buffer = sketch.export(layer, options)

Export an object, using the options supplied.

The method returns:

• undefined if options.output is undefined or a string
• an array of Buffers if objectToExport is an array and options.formats is an image format
• an array of Objects if objectToExport is an array and options.formats is json
• a Buffer if objectToExport is a single item and options.formats is an image format
• a Object if objectToExport is a single item and options.formats is json

import

var sketch = require('sketch/dom')

const layer = sketch.createLayerFromData(buffer, 'svg')

const svgString =
  '<svg width="200px" height="100px" viewBox="0 0 200 100" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><rect fill="#000000" x="0" y="0" width="200" height="100"></rect></svg>'

const group = sketch.createLayerFromData(svgString, 'svg')

Import a file as a Layer.

The method returns:

• a Group if the type is svg or if the type is pdf and the pdf has only one page
• an Image if the type is bitmap
• a Page if the type is pdf and the pdf has multiple pages or eps

find

var sketch = require('sketch/dom')
sketch.find('Shape')

// find all the Shapes in the current Document
sketch.find('Shape')

// find all the Layers in the first Page of the Document
sketch.find('*', document.pages[0])

// find all the Layers named "Layer-Name"
sketch.find('[name="Layer-Name"]')

// find all the Shape named "Layer-Name"
sketch.find('Shape, [name="Layer-Name"]')

⚠️ This API is in preview. It might change in the future depending on the feedback from the community.

Find Layers fitting some criteria.