2createStudio / postcss-sprites

Generate sprites from stylesheets.
MIT License
413 stars 50 forks source link
css postcss postcss-plugin sprites spritesheets spritesmith svg svg-sprites

postcss-sprites Build Status npm version

PostCSS plugin that generates spritesheets from your stylesheets.

/* Input */
.comment { background: url(images/sprite/ico-comment.png) no-repeat 0 0; }
.bubble { background: url(images/sprite/ico-bubble.png) no-repeat 0 0; }

/* ---------------- */

/* Output */
.comment { background-image: url(images/sprite.png); background-position: 0 0; }
.bubble { background-image: url(images/sprite.png); background-position: 0 -50px; }

Usage

var fs = require('fs');
var postcss = require('postcss');
var sprites = require('postcss-sprites');

var css = fs.readFileSync('./css/style.css', 'utf8');
var opts = {
    stylesheetPath: './dist',
    spritePath: './dist/images/'
};

postcss([sprites(opts)])
    .process(css, {
        from: './css/style.css',
        to: './dist/style.css'
    })
    .then(function(result) {
        fs.writeFileSync('./dist/style.css', result.css);
    });

See PostCSS docs for examples for your environment.


Options

stylesheetPath

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

spritePath

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

basePath

Your base path that will be used for images with absolute CSS urls.

relativeTo

Indicates whether the url should be relative against current CSS context or original CSS stylesheet file.

filterBy

Defines filter functions that will manipulate the list of images founded in your stylesheet(s).

Every function must return a Promise which should be resolved or rejected.

Built-in filters:

groupBy

Defines group functions that will manipulate the list of images founded in your stylesheet(s).

Every function must return a Promise which should be resolved with a string or rejected.

Built-in filters:

retina

Defines whether or not to search for retina mark in the filename.

hooks

Defines whether or not to search for retina mark in the filename.

hooks.onSaveSpritesheet

Hook that allows to rewrite the data of produced spritesheet.

If returned value is string, it is used as filepath value, and if returned value is object, it is used as value which will be merged with current spritesheet data.

Returned value can also be Promise which should return either string or object.

hooks.onUpdateRule

Hook that allows to rewrite the CSS output for an image.

spritesmith

A spritesmith configuration.

spritesmith.engine

The engine.

spritesmith.algorithm

The algorithm.

spritesmith.padding

The space between images in spritesheet.

spritesmith.engineOpts

The configuration of the engine.

spritesmith.exportOpts

The export options of the engine.

svgsprite

A svg-sprite configuration.

verbose

Prints the plugin output to the console.


The Image

Every filter or group function will be called with an Image object.

styleFilePath

An absolute path to the stylesheet - /Path/to/your/source/stylesheet.css

path

An absolute path to the image - /Path/to/your/image.png

originalUrl

The url found in your stylesheet including the query params - ../image.png?v1

url

A normalized version of the original url - ../image.png

ratio

The retina ratio of your image - 2

retina

Indicates whenever your image is retina - true

groups

The groups associated with the image - ['shapes', '@2x']

token

The string used as reference in your stylesheet - /* @replace|image.png */

coords

The position & dimensions of image in generated spritesheet - { width: 20, height: 20, x: 0, y: 0 }

spritePath

A relative path to the generated spritesheet - dist/sprite.png

spriteUrl

A CSS url to the generated spritesheet - sprite.png

spriteWidth

The total width of the spritesheet - 200

spriteHeight

The total height of the spritesheet - 400


Advanced


Contributing

Pull requests are welcome.

$ git clone git@github.com:2createStudio/postcss-sprites.git
$ npm install
$ npm run watch