Retina sprite mixins for grunt-spritesmith

Template and grunt-spritesmith options for using sprites with retina support.

Features

• One variable for all sprite elements information instead of variable for each image.
• Using one folder for all sprite images. Better see if you forget retina or non-retina image version.
• One generated scss-file.
• Simple mixins usage without duplicating sprite element's name.

Usage

Preparation

1. Copy spritesmith-retina-mixins.template.mustache somewhere in your project folder.

2. Put all images (both non-retina and retina) in one folder (e. g. img/sprite). Retina version should have same name as non-retina but suffixed with @2x. E. g. play.png and [email protected].

3. Configure grunt-spritesmith's task:

   sprite: {
       buildretina: {
           'src': ['img/sprite/*@2x.png'],
           'dest': 'img/[email protected]',
           'destCss': 'scss/_sprite.scss',
           'padding': 20
       },
       build: {
           'src': ['img/sprite/*.png', '!<%= sprite.buildretina.src %>'],
           // dest should be same as in sprite:buildretina task, but without @2x
           'dest': 'img/sprite.png',
           // padding should be twice smaller, than padding in sprite:buildretina task
           'padding': 10,
           // path to template
           'cssTemplate': '../spritesmith-retina-mixins.template.mustache',
   
           'destCss': '<%= sprite.buildretina.destCss %>'
       }
   }

4. Import generated _sprite.scss to your .scss-file:

   @import "sprite";

In SCSS

Sprite with element size

.retina-sprite {
    @include sprite("scroll-down");
}

Compiles to:

.retina-sprite {
    background-image: url("../img/sprite.png");
    background-position: -199px -57px;
    background-repeat: no-repeat;
    width: 54px;
    height: 23px;
}
@media only screen and (-webkit-min-device-pixel-ratio: 2), only screen and (min--moz-device-pixel-ratio: 2), only screen and (-o-min-device-pixel-ratio: 2 / 1), only screen and (min-device-pixel-ratio: 2), only screen and (min-resolution: 192dpi), only screen and (min-resolution: 2dppx) {
    .retina-sprite {
        background-size: 335px 163px;
        background-image: url("../img/[email protected]");
    }
}

Without element size

.retina-sprite--without-size {
    @include sprite("scroll-down", false);
}

Compiles to:

.retina-sprite--without-size {
    background-image: url("../img/sprite.png");
    background-position: -199px -57px;
    background-repeat: no-repeat;
}
@media only screen and (-webkit-min-device-pixel-ratio: 2), only screen and (min--moz-device-pixel-ratio: 2), only screen and (-o-min-device-pixel-ratio: 2 / 1), only screen and (min-device-pixel-ratio: 2), only screen and (min-resolution: 192dpi), only screen and (min-resolution: 2dppx) {
    .retina-sprite--without-size {
        background-size: 335px 163px;
        background-image: url("../img/[email protected]");
    }
}

Sprite element properties

.retina-sprite-properties {
    @include sprite-width("scroll-down");
    @include sprite-height("scroll-down");
    @include sprite-size("scroll-down");
    @include sprite-position("scroll-down");
    @include sprite-image("scroll-down");
    @include sprite-image-retina("scroll-down");
}

Compiles to:

.retina-sprite-properties {
    width: 54px;
    height: 23px;
    background-size: 335px 163px;
    background-position: -199px -57px;
    background-image: url("../img/sprite.png");
    background-image: url("../img/[email protected]");
}

Example

You can see full usage example at this repo's example folder.

Thanks

Guys from spritesmith's issue about retina sprites for inspiration.

Chris Coyier for retina media query.

License

Copyright © 2014 Aleks Hudochenkov

Licensed under the MIT license.