README

postcss-lazysprite

A PostCSS plugin that generates sprites from the directory of images automatically.

A lazy way to generate sprites and proper CSS with retina support. Feel free to use it :)

Example

Input

/* ./src/css/index.css */
@lazysprite "filetype";

Output

/* ./dist/css/index.css */
.icon-filetype__excel {
    background-image: url(../sprites/filetype.png);
    background-position: 0 0;
    width: 32px;
    height: 32px;
}
.icon-filetype__pdf {
    background-image: url(../sprites/filetype.svg);
    background-position: 0 0;
    width: 32px;
    height: 32px;
}
.icon-filetype__ppt {
    background-image: url(../sprites/filetype.png);
    background-position: -32px 0;
    width: 32px;
    height: 32px;
}
.icon-filetype__word {
    background-image: url(../sprites/filetype.svg);
    background-position: -32px 0;
    width: 32px;
    height: 32px;
}

@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:2dppx), only screen and (min-resolution:192dpi) {
    .icon-filetype__excel {
        background-image: url(../sprites/filetype@2x.png);
        background-position: 0 0;
        background-size: 64px 32px;
    }
    .icon-filetype__ppt {
        background-image: url(../sprites/filetype@2x.png);
        background-position: -32px 0;
        background-size: 64px 32px;
    }
}

File tree

Just a example for above output result, you can dynamic yourself with options.

.			
├── gulpfile.js
├── dist
└── src
    ├── css
    │   └── index.css
    ├── html
    │   └── index.html
    └── slice
        └── filetype
            ├── excel.png
            ├── excel_2x.png
            ├── pdf.svg
            ├── ppt.png
            ├── ppt@2x.png
            └── word.svg

More examples with different options: nameSpace, outputDimensions, dynamicClassBlock, pseudoClass

Features

Simple and easy, just need to put your images to the special folder.
Retina support (@2x, @3x, _2x, _3x are all available).
Support SVG Sprites. Demo
Fully work well with Source Map.
Cache way and good perfomance to run faster.
Support sprites with:hover、:active condition(example).

User

WeChat for Work and Wechat Reader are using postcss-lazysprite in production.

Installation

npm install postcss-lazysprite --save

Usage

Work with Gulp

Example:

var gulp = require('gulp');
var postcss = require('gulp-postcss');
var lazysprite = require('postcss-lazysprite');

gulp.task('css', function () {
    return gulp.src('./test/src/css/**/*.css')
        .pipe(postcss([lazysprite({
            imagePath:'./test/src/slice',
            stylesheetInput: './test/src/css',
            stylesheetRelative: './test/dist/css',
            spritePath: './test/dist/slice',
            nameSpace: 'icon-'
        })]))
        .pipe(gulp.dest('./test/dist/css'));
});

Options

imagePath

Relative path to the folder that sprite images are stored. For resolving absolute images. This option also as the base relative to the value of @lazysprite which is what you output.

Default: null
Required: true

stylesheetInput

The directory that store css(or scss/less) source files. If you are use gulp.js, simply the value of gulp.src without the part of ** and so on.

Default: null
Required: true

stylesheetRelative

Relative path to the folder that will keep your output stylesheet(s). If it's null the path of CSS file will be used.

Default: null
Required: false

spritePath

Relative path to the folder that will keep your output spritesheet(s).

Default: ./
Required: false

nameSpace

NameSpace(Prefix) of the class name of each image.

Default: null
Required: false

logLevel

Deside which level to output log. Can be either "debug", "info", or "silent".

// Show me additional info about the process
logLevel: "debug"

// Just show basic info
logLevel: "info"

// output NOTHING except alert
logLevel: "silent"

Default: info
Required: false

cssSeparator

Separator between css selector's 'block' and 'element'. In this plugin. 'block' is equal to file dirname or dynamic one, 'element' is the base name of file.

Default: '__'
Required: false

retinaInfix

Deside the created sprite retina file is whether '@2x' or '_2x' as part of name.

Default: @
Required: false

outputExtralCSS

Deside whether output extral css details, which list like:

.icon-filetype {
    display: inline-block;
    overflow: hidden;
    font-size: 0;
    line-height: 0;
}

when set this option as true, the html sould like:

<i class="icon-filetype icon-filetype__doc"></i>

Default: false
Required: false

pseudoClass

If the file naming with Hoveror Active as suffix，it will turn to the :hover or :active pseudo class.(example)

Default: false
Required: false

outputDimensions

Deside whether output width & height properties.

Default: true
Required: false

keepBackGroundSize

add background-size attribute when 1x.

Default: false
Required: false

Contributing

Thanks the inspirations from postcss-sprites plugin.

Issues and Pull requests are welcome.

$ git clone https://github.com/Jeff2Ma/postcss-lazysprite
$ cd postcss-lazysprite
$ npm i
$ gulp # for dev
$ gulp test # for test

Usage no npm install needed!