How to build your first Sketch plugin

Sketch plugins open up so many opportunities for creative and new ideas. As you probably have found, plugins can do a wide variety of things such as automate existing features, provide new interfaces, get data from external locations, and more! Let’s dive into some of the very basics of plugin development.

The only thing you need for this tutorial is a copy of Sketch. A little knowledge of Javascript won’t hurt either, but if not, that’s ok, I’ll be describing each step along the way. First, you will learn how to use Sketch’s script panel. By the end, you will have made a plugin that will create some awesome shapes and be well on your way to building plugins of your own.

The Script Panel

Getting started is super simple. Open up Sketch and navigate to Plugins > Run Script...

This is the script panel. It’s a little space to test your code quickly. Inside the panel you’ll find some example code already written for you.

Here is that code in a little nicer format in case you need it again.

Sketch’s JavaScript API — Breaking down the example code

The Sketch JavaScript API is a way for us to interact with Sketch via code. Hereafter we will simply refer it to the JS API. With the JS API you can manipulate layer properties, select layers based on complex rules, export assets, and more!

To start things off let’s click the “Run” button and see what happens. This will help us get an idea what is going on.

Once you click “Run” a few lines appeared in what is called the console.

The first two lines are pieces of text and the last line tells us how quickly our script took to run. You will often see messages like this in the console. Other times you will see helpful error messages in debugging your code.

To get a better sense of how what is actually going on let’s look over the example code. The first line starts with this:

This logs some text (or a String) to the console. You will often use console.log(‘something’) for checking to make sure your code behaves as expected. This is how that first line in the console was printed.

The next line is this:

This is the way you import the JS API. We will need this bit if we want to interact with Sketch.

getSelectedDocument() is a method defined on our object sketch. It returns the selected document or null if there are no documents selected.

Here we get the selected layers from the selected document. This is a very, very common pattern so be sure to remember that to get the selected layers you will need to do so through the document object. The length property gets the number of layers that are selected.

*One small note here for those that have a bit more Javascript experience. selectedLayers isn’t an array but rather a Selection class. If you want to get an array of the layers selected you can do so by using the Selection class’ layer property:

Last but not least, is checking to see if there are any layers selected and if so, logging the names of the layers.

First, we check if the number of layers is 0. If true, then we log the text “No layers are selected.” If the number of layers isn’t 0, we then log the text “Selected layers:” to prefix the list of layer names that we are going to log.

After that, for each layer we log the layer index and layer name. More specifically, we use the forEach method on selectedLayers. We pass in a function which takes two inputs: the layer and the index. Since the first layer index starts at 0 we add 1 to it so we can get the log output to look like this:

Hit the Road Running

Now that you know how the code works, hit the run button in the bottom right! See if you can trigger the different console messages. If you have no layers selected, then when you run the plugin you should see the text “No layers selected” in the console. If you did have some layers selected before running the script then you will see their names reported in the console. Pretty cool huh? Ah, we are just getting started…

Drawing Shapes

Drawing shapes is one of my favorite things to do in Sketch. Some days though, even drawing rectangles is too hard. On those days I really wish Sketch could do that for me. Let’s see if we can build a plugin that helps me when I’m lacking some inspiration. This is what we will make:

In this next part we will learn how to create an artboard, make some shape layers, group them together, and reorder them. Follow along and let’s go!

1. Import Sketch & Get Common Objects

Once you have your script panel open and ready to go, the first thing that we need to do is to import the JS API. Remember, this is what helps us interact with Sketch.

Then, we will need to get the current document and page. To get the current page we use a method on sketch and get the selected page as a property on document.

2. Create an Artboard

The other neat thing that you can do with the JS API is to pull out various useful Sketch objects from it. I like to think of the JS API like a utility belt which has lots of neat tools. In practice, you use it to pull out various classes from it. A class is a special type of function that organizes related functions and properties (you can learn more here). Here is how we pick out the Artboard class.

Now, we can use the Artboard class — the tool we just pulled out — to create an actual instance of an Artboard:

and if you log myArtboard you will see that you successfully created an Artboard object!

✔️ Checkpoint

Let’s take a brief moment to see what we have written. Your code should look like this so far:

It’s good practice to move dependencies, or the imported tools, to the top of the file. Let’s move the Artboard class to the top.

One other thing we can check is to see what myArtboard looks like. If we add console.log(myArtboard) to the end of the script and hit “Run” the logged output should look like this:

So now that we created the artboard you might be thinking,“Well…where is it exactly?” If you look underneath your script panel you should see that nothing got added to the canvas (you can also close the panel and look around to be sure — as long as you clicked “Run” your written code will still be there for you when you open the script panel again).

It turns out that we will need to explicitly attach the artboard to the correct page. Otherwise, the artboard object that we made will be thrown away once the script is done running. This is why if you keep hitting the Run button over and over the unique id value of the artboard will change. Sketch is creating a brand new artboard object each time your script is executed.

To attach the artboard to the page we will need to specify a parent:

Or if we want to be a bit more succinct about it we can pass the parent property when we initialize the artboard.

Sweet! We got our artboard on our canvas. But, our artboard is a little small. In fact, the default size is 100 by 100. Perhaps you have an idea how to make the artboard larger already. If we look back to when we logged myArtboardthen you might have noticed this property:

So to resize our artboard to 400px by 400px we can modify myArtboard like so:

Which we can also move into the initializer:

Nice work! By now you have clicked the Run button a few times and it’s likely that you have created a few artboards on top of one another. Or maybe you have been deleting them every time you wanted to run the code again. That is a bit tedious and something we can do programmatically! To clear everything within a page you can do this:

If we add that before we create our artboard then each time you run the script the previously made artboards will be removed.

So if we put everything together so far we should have something like this:

Great job! Now let’s add some shapes!

3. Creating a Square

Creating a square is very similar to creating an artboard. We willspecify a frame, a parent, and now a fill! Here is how we do it:

We are already familiar with parent and frame. style is the newest of the bunch. If we take a look at the inspector panel inside Sketch we can get an idea of what our code is doing.

When you select a layer, there are a bunch of properties like Resizing, Prototyping, Appearance, Style, Shadows, Inner Shadows, Blurs, etc. We want to add a fill which is under the Style section.

Fills can be disabled or enabled, have a blend mode, a hex value, and opacity. You can also have multiple fills as well!

Since you can have multiple fills the fill property holds a list of them (in code, a list is often called an array). That looks like this:

But since we really only want one fill we just need to pass in one hex value.

Before we move on to creating other shapes I want to point out one subtle detail with frames:

Since we specified the parent artboard, the frame that we provide will be relative to the artboard that we made (it also inserts it inside the artboard as well). If we made the parent the page like we did when creating the artboard then its coordinates would be relative to the page.

✔️ Checkpoint

So, to review what our code should look like at this step, it should look like this:

Let’s move the ShapePath class up to the top to keep our dependencies together.

That is looking really great! If you click “Run” this is what should appear on the canvas:

*Note: If your square has a border around it then its likely that your Default Layer Style is causing this. To ensure that a border won’t be drawn you will need to pass in an empty array for borders like so. This will likely be fixed in later versions of the Sketch API.

4. Creating Other Shapes

Triangles

Creating other shapes like triangles, pentagons, and circles are really similar to drawing rectangles. We need to specify a parent, a frame, and a fill (well a style that contains a fill). The only difference now is that we need to specify a ShapeType:

ShapePath contains an object called ShapeType. If you log ShapePath.ShapeType you’ll find a list of all the different types of shapes you can create. Here we want to use the Triangle option.

Also, you might have noticed that there is a funny looking Hex code here. Normally Hex codes are 6-digits and correspond to RGB values (two digits for each color channel). 8-Digit hex codes have some extra bit of information and use the last two digits to encode opacity. Specifically, the b3 part of the string corresponds to 70% opacity.

*If you are looking to learn more about hex codes then check out these resources:

Pentagons

Now that you know how to change the shapeType how might you be able to create a pentagon? The trick is to use the Polygon option.

The default number of sides of a polygon is 5. Unfortunately, you can’t change the number of sides with the JS API just yet so we are stuck with hexagons for now.

Circles

Circles, of course, are created with the OvalShapeType. Hah! You thought it was going to be Circle, eh? I made the same mistake when writing this post out 🙃. In hindsight it makes sense though because ovals are more generic than circles. To create a circle rather than an oval we just make the width and height the same.

Notice that we specify just the border and no fill. This will create a 1px border. To specify a border width we will need to change things a little. Rather than just specifying a hex value for the border properties we also need to pass in the thickness.

Here is how we add those extra properties:

✔️ Final Checkpoint

We have put everything together now! You can check your code below:

If you want to save your script as a plugin you can do so with the “Save Script As Plugin” button.

A quick word of caution though before you do so. Because we are resetting all the layer contents of our document each time with page.layers = [] (on line 8) it can be pretty destructive to any documents that have actual work in them. As such, you might want to remove that line before converting your script to a plugin.

One you do save your script as a plugin it will appear under Plugins > Your Plugin Name > Your Plugin Name . We’ll cover how to edit this saved plugin in another article. For now, great work on making your first plugin! The next section covers some additional concepts that are extremely helpful when managing created layers.

Additional Topics

Reordering Layers

Often times you want to put your shapes in exactly the right order. There are a few ways to go about doing this.

  • Move the layer to the front or back
  • Move a layer forward/backward
  • Specifying the index

Note that the layer at the back of the parent (visually) will be layer 0. The layer at the front will be layer n -1 where n is the total number of layers in the parent.

Grouping Layers

Grouping layers will feel really similar to setting up an artboard. First we have to pull Group out like so:

Just like creating an artboard, we create a new group like this:

Note that we don’t need to specify a frame here. The layers inside the group will determine the frame if we use a special little method called adjustToFit()

However, if you attempt to add all the layers to a group at the end of the script that we have been working on you might notice some funny business.

Honestly, I’m not entirely sure what is going on here but it seems related to the fact that the layers have more than one parent (one to the artboard and other to the group). To fix this, ensure that the layer you’re adding to a group doesn’t already have a parent. If it does, you’ll need to remove it from its existing parent first using remove(), then adding it to it’s new parent. (This is actually a bug)

Next Steps

Congratulations! 🎉 You have accomplished a lot so far! Now you might be wondering how to take it a step further. Here are a few suggestions:

  • See what cool art you can make. If creative coding is something that you want to dive into then I would highly recommend Processing, a language dedicated to making graphics and animations programatically.(Here is a piece I made for this article)
  • Learn more about the Sketch JS API. This is how I learned what functions and properties are available with each of the objects.
  • Get involved in the community. Lots of designers and developers are asking questions and sharing code over at the Sketchplugins forum and on Spectrum.

Lastly, if you have an idea for a plugin but just aren’t sure how to write it, share it in the comments below and I can point you in the right direction.If enough people have similar questions, I’ll write a blog post about it!

Until next time! 💎

Building things for education with @gradescope

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store