in Development

Getting started with Grunticon

Grunticon is good alternative to icon fonts. It uses SVG files and embeds them in a CSS file that makes it super useful for web project. It’s a bit tricky to set up, so we created this guide to help you get started.

What is Grunticon?

Before we introduce Grunticon, we need to introduce Grunt. Grunt is a task runner for automating repetitive tasks on your computer such as converting images. You can read more about Grunt on their website.

Grunticon is a Grunt task that makes it easy to manage icons by generating the CSS necessary to integrate the icons in your web project. From a CSS perspective, it’s easy to use, as it generates a class referencing each icon, and doesn’t use CSS sprites.


If you want to see what this tutorial will end up with, try out the demo. This tutorial helps you create a very useful workflow for adding icons to your webproject – take a look:

Let’s say we want to use 10 icons from Webalys’ Streamline icon set. We place the 10 icons in a specific folder.


When I run the command grunt from the terminal, the output folder is populated with CSS-files and a PNG folder.


After adding a small snippet to the <head> element of my web page, I’ll be able to use the icons by using the class names icon-app, icon-book, icon-coffee etc. Grunticon adds the icons to the CSS file and wraps them in classes based on a prefix, icon- and the filename.

So the following element will show the bag icon in 48×48 px.

Adding the app, book and coffee icon using only HTML:


Grunticon converts the SVG icons to PNG icons as well, so when the browser doesn’t support SVG it falls back to the PNG version. Pretty neat!

So let’s get started. Here are 10 steps to getting Grunticon up and running on your computer:

Installing Grunticon

Firstly, you’ll need to install the Node.js package manager (npm) if you don’t have it already. Here are a guide for installing npm for Windows and for Mac OS X.

Adding package.json

Next we need to add the package.json. This tells npm what to install.

Navigate to the root of your web project and create a new file and add the following to the file:

You can download the package.json used in this example.

Install Grunt and Grunticon

Now that we have added the package.json, we need to run npm to install the dependencies. Open the terminal or command line and navigate to the root folder of your web project and run the following to install Grunt globally, so it’s easy to run:

And then run the following to install the local dependencies for our Grunt file:

You should see a message confirming the Grunt and Grunticon have been installed.

Adding Gruntfile.js

Now that we have Grunticon installed, we need to tell Grunt to run Grunticon for your project. In the root folder of your project, add a new file called Gruntfile.js.

For this tutorial we will use the following configuration:

You can download the Gruntfile.js used in this example and find additional documentation about setting up the Gruntfile on Github.

Create folders

We need two folders, one for the SVG files we want to use and one for the generated CSS and PNG files. In the root folder of your project, create a new folder named grunt with two subfolders named svgs and output.

You should end up with the following:


You can basically arrange the folders as you like. Just make sure to update the cwd and dest variables in the Gruntfile to match the setup you like.

Important: You should not add anything to the output folder your self, since Grunticon by default will overwrite the content in that folder.

Add SVG files to the svgs folder

Now, add some icons in SVG form to the `svgs´ folders. You can download some nice icons from the Streamline icon set.

Run Grunt to convert files

From the terminal / command line, run

This should output something like:

Your SVG have now been embedded in a CSS file along with PNG versions for the fallback CSS.

In these CSS files you’ll find the class named .icon-<filename>. So if you had a file named wifi.svg in the svgs folder, it can now be added as a background image to HTML elements by adding the class icon-wifi to the given element.

If you open the file preview.html in the output folder you can see all the icons added to HTML elements.

Including the CSS files to your project

To include the CSS files to your project, add the following snippet to the <head> element. This snippet is available in the grunticon.loader.js file in your grunt/output folder.

Important: Make sure the paths in the both the <script> and <noscript> tags are correct.

Adding classes to the HTML elements

You should be able to add icons to elements in you HTML. You can do this by adding the class with the prefix icon- combined with the filename.

Adding a bit of CSS, we now have some nice buttons with icons. Try out the demo.


Adding new icons to your project

When you add new icons or edit existing icons, make sure to only add them to the svgs folder and not the output folder.

It’s necessary to run the grunt command from the root folder of your web project to generate new CSS and PNG files.

Change default width and height

You can change the default size of the icons added to the CSS file by changing the options in the Gruntfile. For more documentation about the options, please visit the Grunticon documentation.

Please let us know in the comments if you get stuck in the tutorial.

Write a Comment



  1. Am I misunderstanding something? The CSS is applying the SVGs as a background images so changing the width and height (to a smaller value) on the div just crops out the image. Is that correct?

      • Ah ok. I guess I was confused because I thought this was a drop-in replacement technique for icon fonts (which you can live resize). This requires you to generate the exact size of SVG (and fallbacks) ahead of time which seems of limited use to me.

        I look forward to your follow up. In the mean time, I’m enjoying all your other terrific tutorials.

        • You can. I think it’s only a matter of customizing the output of Grunticon. E.g. adding background-size: cover; or background-size: contain; to the CSS would make the icon fit into the container. So if you change the size of the container using the icon as an background image, the icon will scale with it.

  2. Great tutorial! Very easy to follow and to the point. One question – how does it work wirh an icon set that has mixed heights and widths?

  3. Seeing this article reccomended on Smashing Magazine’s Facebook seems like the universe’s way to tell me: switch to SVG! This article has been the most clear to me regarding Grunticon so far, but since the web I’m currently building has some users on old technology I’m still hessitating. Great read, def. going to my favs!

    • Thank you – we’re happy to hear you liked the tutorial.

      Regarding backwards compatibility. The Grunticon script exports the SVG icons as PNG. When the browser does not support SVG, it will use the PNG files as fallback.

  4. This is very useful Martin, I’m currently designing a platform fo enterprise apps and we have used many font icons when we need to but for purposes of branding we ended up creating our own icons and the more and more we create branded icons the more we need some way to manage them , just be able to change the graphic to try new ones and of course having them in a different stylesheet with all the base64 encoding, doing that manually for each one of them is hideous and our custom icons have a lot of detail which is a lot of code certainly. Thanks.

  5. One of the advantages of icon fonts over images/sprites is the ability to change the icon color easily in the CSS. For example, if you had a icon in a button, and you needed the color of the icon to change on hover. If you’re using an icon font, this is easy. How would you accomplish something like this with this approach?

  6. I am having some trouble with the plug-in. For some reason after I run the grunticon function it still doesn’t produce the end results. I followed the instructions on your blog post and then did the same thing on, no change in the end results.

    I then thought it wouldn’t pull up the results on my local machine so I upload the files online, same thing no results.

    I finally went into the example folder provided in the grunt-grunticon folder to compare my work to the working example. Nothing I saw looked out of place.

    Does grunticon not operate in the latest version of grunt or did I miss something in my .json file?

    “grunt”: “^0.4.5”,

    module.exports = function(grunt) {


    grunticon: {
    myIcons: {
    files: [{
    expand: true,
    cwd: ‘www/svg’,
    src: [‘*.svg’, ‘*.png’],
    dest: “www/icon-test/”
    options: {

    loadersnippet: “grunticon.loader.js”,


    grunt.registerTask(‘default’, [‘grunticon:myIcons’]);

  7. This worked like a charm for me. Only issue i’m having is that it adds the .icon- to the beginning of each class name. Can I turn that off somehow?

    Thanks again!

    • You can specify an option in the options array:


      Type: String Default value: “.icon-”

      a string to prefix all css classes with.

      options: {
      cssprefix: ‘ ‘


  8. Is there a way to customize how your generated css file is created? Does it allow you to use a template? Can you show a break down of that if you have time? Thanks!