Creating a sublime text snippet

September 1, 2014

Sublime comes standard with quite a few snippets, and if you install the Emmet package you get tons more. However, custom snippets can be incredibly handly. This article explains how to create a Sublime Text snippet with a custom hot key trigger that will allow you to seamlessly dump your snippets of code anywhere you need them.

Step 1: Create a new snippet

Go to Tools > New Snippet…. This will bring up a new tab in Sublime that looks like this:

sublime text snippet default template

Step 2: Add your code

What we need to do is remove the following: Hello, ${1:this} is a ${2:snippet}. and replace it with your snippet of code. Your code should actually go between the <content><![CDATA[ and ]]></content>.

This screenshot shows a big fat html comment as the content of this example snippet.

new sublime snippet

There are a few notable parts that were added besides the content of the snippet including: (1) cursor placement, (2) a tab trigger, and (3) a description, all of which I’ll cover in a moment.

Step 3: Tab Trigger

The tab trigger is a critical part of the snippet. Without it, you have to use your mouse and the menu to insert the snippet by navigating to Tools > Snippets. This might be well and good for Sunday drivers, but using the menu is a detriment to a fast workflow.

The tab trigger, however, is a beautiful feature. The snippet template defaults with code that looks like this: <!-- <tabTrigger>hello</tabTrigger> -->. Remove the html comments that wrap the tabTrigger tag and replace the text ‘hello’ with the text for your shortcut. For a big superman html comment, I am using ‘super’ as the tab trigger: <tabTrigger>super</tabTrigger>.

We have a few more steps before we save this snippet, but once it’s all saved, to activate the tab trigger just type the trigger and press the tab key. So I would type ‘super’ and press tab to seamlessly drop in my snippet. But we’re not there yet. Let’s keep moving.

Step 4: The Description tag

The description tag is not a part of the default snippet template, but you can add it in to name your snippet. This might be nice if you forget the tab trigger, you could go to Tools > Snippet… and find it based on the description you gave it.

It may also be a good idea to use the same description as tab trigger, this way if you forget the tab trigger you can figure it out by the description

snippet description

Step 5: Cursor Placement

You may think that after a snippet is inserted in to your code that your cursor will land immediately following the snippet. That is not entirely correct. A great part about snippets is you can determine where the cursor will be placed by using $1. When you drop in your snippet the $1 will vanish and your cursor will be in its place. You can also specify multiple cursor placements by using $1, $2, $3 etc. When the snippet is dropped in, your cursor will start in position 1 and your tab key will move it to position 2, then 3, etc.

multiple cursors in a sublime snippet

Step 6: Saving

Save the snippet file with any name you like, but the file extension must be .sublime-snippet. Where you save it matters as well. Depending on where you installed your copy of Sublime this path may change: Macintosh HD > Users > Rich > Library > Application Support > Sublime Text 3 > Packages > Users > your-snippet-name.sublime-snippet, where ‘Rich’ would equal your computer’s name. Luckily, when you create a new snippet and save it (the same way you would save any other file in Sublime) it usually defaults to the proper save location. But if you needed to edit a snippet you would need to know this location in order to open the file and edit it.

save snippet location

After you save it, you may have to close Sublime and re-open it before it will be recognized.

There’s two other things worth noting when it comes to snippets: Escaped Characters and Scope.

Escaped Characters

Let’s say you want to drop in some jQuery, something like this:

$("$1").on("click", function(event){
    $("$2").addClass("$3");
});

The problem is the $ that jQuery uses as part of its syntax. The dollar sign is also a special character in Sublime’s snippets, so we have a bit of a conflict. Now you could substitue all the $’s with the word jquery, but thats kind of weird. So the better solution is to escape the $’s by preceding them with a \. So your snippet code would look like this:

\$("$1").on("click", function(event){
    \$("$2").addClass("$3");
});

Scope

In theory scope is super simple. If no scope is provided the snippet will be used in all document types (i.e. .html, .css, .js, .php, etc.). If a scope is provided, the snippet will only be used in that document type. So using the scope text.html should make the snippet only trigger in .html documents.

snippet scope

In reality scope is kind of a pain in the @$$. Becuase it doesn’t always work as expected. Let me get to that is a second. For now, some common scope’s include:

Here’s a list of scope’s for reference. Most scope’s start with ‘source’ and end with the file extension with the exception of html files. To determine the scope of a certain document type you can also open that document and use the hot key SHIFT+CTRL+P on mac. In the very bottom left you’ll see the scope appear for a few seconds before it dissapears.

press SHIFT+CTRL+P to see the scope

Don’t be alarmed if you can’t get the scope to work perfectly for you. I tend to have trouble with it, so I normally let the snippet default to all documents. Which is normally good, because let’s say you want to drop your jQuery snippet in an html, php, or cfm file? You’re not always dropping it in an external javascript file so limiting it’s scope to just javascript can potentially be a bad thing because you wouldn’t be able to use your snippet anywhere you wanted to.

That’s it!

Create the code snippets you need with a memorable tab trigger and you’ll be much happier.

Mastering CSS: Book by Rich Finelli
Mastering CSS, the Book! Flexbox, Layout, Animations, Responsive, Retina, and more!
Mastering CSS, 2nd Edition, video course by Rich Finelli
Mastering CSS, Second Edition: 47 videos on how to make websites like a boss! Flexbox, Animations, Responsive, Retina, and more!
  • Kristin

    Thank you for this post. But, there is no option for “New Snippet” in my Tools menu. Only “Snippets …”. It isn’t clear how to proceed from there. And, why isn’t that option showing in my menu? Any thoughts or suggestions are greatly appreciated!

    • Rich

      Hi Kristin – you’re right, the moved it. It’s now located under Tools > Developer > New Snippet. They must have changed it in an update.

  • sandeep kamara

    Hello Sir
    This is the very helpful to create a sublime snipett.

Back to top