Need help with SketchAPI?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

788 Stars 123 Forks MIT License 2.0K Commits 78 Opened issues


The JavaScript plugin library embedded in Sketch

Services available


Need anything else?

Contributors list

Sketch API

This is a JavaScript API for Sketch. The intention is to make something which is:

  • Idiomatic 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.

This API is a very core layer which interfaces with Sketch itself. It's intentionally simple, and we want to keep it that way. If you feel like adding some high-level code to it, it’s probably better to add it to a community-maintained library that can be used on top of the API, and keep it separate from the core API effort.

API layers

Comments and suggestions for this API are welcome - file an issue to discuss it or send them to [email protected]


The full documentation is available on

Here's a very simple example script:

// access the Sketch API - comes bundled inside Sketch, so no "installation" is required
var sketch = require('sketch')

// get the current Document and Page var document = sketch.getSelectedDocument() var page = document.selectedPage

var Group = sketch.Group var Shape = sketch.Shape var Rectangle = sketch.Rectangle

// create a new Group belonging to the current Page var group = new Group({ parent: page, frame: new Rectangle(0, 0, 100, 100), name: 'Test', selected: true, }) // create a new rectangle Shape belonging to the previously created Group var rect = new Shape({ parent: group, frame: new Rectangle(10, 10, 80, 80), })

// get the current selection var selection = document.selectedLayers

console.log(selection.isEmpty) selection.forEach(function (item) { console.log( })

// deselect all the layers selection.clear() console.log(selection.isEmpty)

// select the rectangle we created rect.selected = true console.log(selection.isEmpty)

// ask the user for a string sketch.UI.getInputFromUser( 'Test', { type: 'String', initialValue: 'default', }, (err, outputString) => { if (err) { return } // store the string in the settings // it will be remembered even when Sketch closes sketch.Settings.setSettingForKey('setting-to-remember', outputString) console.log(sketch.Settings.settingForKey('setting-to-remember'))

    type: 'Selection',
    possibleValues: ['Sketch', 'Paper'],
  (err, outputSelection) => {
    if (err) {
    sketch.UI.message('Hello mum!')
    sketch.UI.alert('Title', outputSelection)

} )

For more examples, we recommend checking out the examples section of the developer website.

Happy coding!


This section of the readme is related to developing SketchAPI locally. If you're just interested in using SketchAPI to write Sketch Plugins you can stop reading here.

You'll need the following tools available on your system to work on this repository:

  • Node 10 or greater
  • Visual Studio Code (recommended)


SketchAPI is written in JavaScript, as a collection of files in the


Webpack is used to bundle the files, and we include this in each release of Sketch. However you can build, run and test SketchAPI locally too - continue reading to find out how.


The following npm scripts are available. Carry on reading below for more in-depth guides.

| Script | Description | | ----------------------------- | --------------------------------------- | |

npm run build
| Build SketchAPI into the
folder | |
npm run test
| Run the integreation tests using skpm | |
npm run lint
| Lint the source code | |
npm run format-check
| Check the format with Prettier | |
npm run api-location:write
| Tell Sketch to use your local SketchAPI | |
npm run api-location:delete
| Undo
npm run api-location:write

Build and run

Following these steps will allow you to build the source files, and inject the changes into your local copy of Sketch to see the results.

Any plugins you have installed or code you invoke in Sketch's Plugins > Run Script dialogue box will run against your changed version of SketchAPI.

  1. Checkout this repository.
  2. Make your copy of Sketch use your local version of SketchAPI, rather than the one it has built-in.
    npm run api-location:write
  3. Ensure you've installed the dependencies with npm, and then build SketchAPI.
    npm install
    npm run build
  4. Start Sketch and your changes will be picked up.

⚠️ If you re-build SketchAPI by running

npm run build
again while Sketch is open you won't see your changes automatically reflected. You'll need to restart Sketch for this to happen.

⚠️ Once you've finished working on SketchAPI don't forget to stop Sketch using your customised version, to do this run:

npm run api-location:delete



files in this repository are integration tests that run in Sketch's plugin environment, using the skpm test runner.

To run these tests using your current version of the Sketch as the host environment invoke:

npm run test

Alternatively if you want to run the tests with a specific app binary run:

SKETCH_PATH=/path/to/ npm run test

ℹ️ There is no need to re-build SketchAPI between test runs or use

defaults write
to set the API location; the test runner handles re-compiling test and source files and injecting them into Sketch.


The API documentation is part of the

Make sure to update the API and the action reference accordingly when you make changes to the API.


We would like to thank:

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.