0.4.7 • Public • Published


    Uses grunt-spritesmith along with some image-manipulation and SCSS-trickery to generate HD-compatible sprites and corresponding SCSS stylesheets.


    grunt-spritesmith — allows for a variety of spriting engines (check out its requirements).

    grunt-spritesmith-hd, though, is more restricted. It uses GraphicsMagick for Node for image processessing, and that requires that you already have either GraphicsMagick or ImageMagick installed. (Note that if you have installed ImageMagick and not GraphicsMagick, you need to specify this in the resizeEngine setting.)


    This plugin requires Grunt ~0.4.0

    If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

    npm install grunt-spritesmith-hd --save-dev

    Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:


    SpriteHD Task

    Run this task with the grunt spriteHD command.

    First, have a look at the configuration options available for grunt-spritesmith. Most of those relate to grunt-spritesmith-hd — except cssFormat and cssTemplate, since this plugin relies special SCSS.

    (If you would like grunt-spritesmith-hd to be more flexible, please contribute!)

    Unlike the original grunt-spritesmith, this plugin utilizes Grunt's options, so you can pass the same options to multiple targets.

    Required Parameters

    The following parameters must be defined for every target.


    Type: String | Array

    The assets that will be aggregated into your sprite.


    Type: String

    A name that will designate your sprite's files.

    For example, if you were to provide the spriteName "genuflect", your sprite images would end up as hd-genuflect.png and ld-genuflect.png and your stylesheets would be _sprite-genuflect.scss and _sprite-genuflect-hd.scss.


    As with other Grunt tasks, these options can be task-wide or target-specific.

    All of these options are optional, because they all either have default values or can be ignored.


    Type: Boolean Default: true

    Do you want your spritesheet high-def-ready? Are your sprite assets 2x the size that they will appear?

    Set to false if your sprite assets aren't up for it.

    If hd is false, grunt-spritesmith-hd will simply run grunt-spritesmith with the parameters and options you've passed.


    Type: String Default: images/sprites

    A directory where your generated sprite image(s) will go.


    Type: String Default: style/scss/sprites

    A directory where your generated SCSS file(s) will go.


    Type: String Default: hd

    A prefix for your high-def sprite files.


    Type: String Default: ld

    A prefix for your low-def sprite files.


    Options: gm, im Default: gm

    The engine that will be used behind-the-scenes for resizing. Defaults to GraphicsMagick; but if you only have ImageMagick installed and want to use that, instead, specify it here.


    Options: top-down, left-right, diagonal, alt-diagonal, binary-tree Default: binary-tree

    A packing algorithm to use. See details in grunt-spritesmith's documentation.


    See details in grunt-spritesmith's documentation.


    Type: Number Default: 1

    Padding to be placed between images on the generated spritesheet(s).


    Options: auto, phantomjs, canvas, gm Default: gm

    Specify your spritesmith engine. See details in grunt-spritesmith's documentation.


    Type: Object Default: {}

    Specify settings for your engine. See details in grunt-spritesmith's documentation.


    Type: Object Default: {}

    Specify image processing options. See details in grunt-spritesmith's documentation.


    Type: Array Default: ['.png', '.jpg', '.jpeg']

    Accepted extensions for your sprite assets.


    Type: String Default: The default value is the relative path between your destCSS and destImg directories.

    Manually override the sprite image's path in the generated stylesheet's background-image url(s). Here are a couple of use cases:

    • If the relative path from your destCSS directory (where the SCSS files go) to your destImg directory (where your sprite images go) will not be the same as the relative path from your compiled CSS to destImg.
    • If you will be hosting the images elsewhere, eventually, on a CDN or something.


    Type: Object Default: {}

    Options to pass to the Mustache template that generates your stylesheets.

    • { functions: false }: the generated SCSS includes variables only, not mixins. This is handy if you are using multiple sprites in a project and don't want to duplicate the mixin definitions.
    • { createMap: false }: If true, will create a variabble map in the SCSS file
    • { varPrefix: none }: String value to set a prefix for the variables in the generated SCSS


    Type: Boolean Default: false

    Set it to true in order to interrupt the build process if any of the standard source images size (width or height) is not even.

    If it's set to false the build process just raise a warning.

    All the images should have an even height and an even width (e.g. 22x26px)


    Type: String Default: undefined

    The default results in the use of the default template for the scss extension of json2css. You can pass a path to a template that is then passed to grunt-spritesmith as the cssTemplate option. The path can be relative to the directory where you call grunt or relative to the tasks directory of grunt-spritesmith-hd.


    Type: String Default: path.join(__dirname, 'templates/scss-hd.template.mustache')

    If you don't pass this option, the scss-hd.template.mustache from grunt-spritesmith-hd is used. You can pass a path to a template that is then passed to grunt-spritesmith as the cssTemplate option. The path can be relative to the directory where you call grunt or relative to the tasks directory of grunt-spritesmith-hd.



    spriteHD: {
      options: {
        destImg: "sprites",
        destCSS: "scss/sprites",
        imgPath: "sprites"
      all {
        src: ["images/sprite-assets/all/*"],
        spriteName: "all"
      home: {
        src: ["images/sprite-assets/home/*"],
        spriteName: "home",
        options: {
          cssOpts: {
            functions: false,
            createMap: true,
            varPrefix: 'icon-medium'

    combined scss maps:

    This uses the template at

    spriteHD: {
      options: {
        destImg: "sprites",
        destCSS: "scss/sprites",
        imgPath: "sprites",
        hdCssTemplate: 'node_modules/json2css_scss_combined_maps/scss_combined_maps.template.mustache',
        ldCssTemplate: 'templates/scss_combined_maps-hd.template.mustache'
      all {
        src: ["images/sprite-assets/all/*"],
        spriteName: "all"
      home: {
        src: ["images/sprite-assets/home/*"],
        spriteName: "home",
        options: {
          cssOpts: {
            functions: false

    Using the Output

    After running grunt-spritesmith-hd, in your destCSS directory you will find an unprefixed SCSS file — that is the one you should import into your own SCSS/Sass.

    For example, a typical HD sprite with the spriteName "everything" will output _everything-hd.scss and _everything.scss into destCSS. You need to @import "path/to/everything".

    (If you look inside _everything.scss, you'll see that already imports _everything-hd.scss, so you don't have to worry about it.)


    npm i grunt-spritesmith-hd

    DownloadsWeekly Downloads






    Unpacked Size

    24.3 kB

    Total Files


    Last publish


    • benib
    • davidtheclark
    • fgiust
    • openmindlab