2createstudio
postcss-sprites 
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.
- Default: null
- Required:
false
spritePath
Relative path to the folder that will keep your output spritesheet(s).
- Default:
./ - Required:
true
basePath
Your base path that will be used for images with absolute CSS urls.
- Default:
./ - Required:
false
relativeTo
Indicates whether the url should be relative against current CSS context or original CSS stylesheet file.
- Default:
file - Required:
false - Options:
file|rule
filterBy
Defines filter functions that will manipulate the list of images founded in your stylesheet(s).
- Default:
[] - Required:
false - Options:
Function|Function[]
Every function must return a Promise which should be resolved or rejected.
Built-in filters:
- based on
fs.statand used to remove non exisiting images
groupBy
Defines group functions that will manipulate the list of images founded in your stylesheet(s).
- Default:
[] - Required:
false - Options:
Function|Function[]
Every function must return a Promise which should be resolved with a string or rejected.
Built-in filters:
- based on
@2xnaming convention
retina
Defines whether or not to search for retina mark in the filename.
- Default:
false - Required:
false
hooks
Defines whether or not to search for retina mark in the filename.
- Default:
{} - Required:
false
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.
- Default:
null - Required:
false
hooks.onUpdateRule
Hook that allows to rewrite the CSS output for an image.
- Default:
null - Required:
false
spritesmith
A spritesmith configuration.
- Default:
{} - Required:
false
spritesmith.engine
The engine.
- Default:
pixelsmith - Required:
false
spritesmith.algorithm
The algorithm.
- Default:
binary-tree - Required:
false
spritesmith.padding
The space between images in spritesheet.
- Default:
0 - Required:
false
spritesmith.engineOpts
The configuration of the engine.
- Default:
{} - Required:
false
spritesmith.exportOpts
The export options of the engine.
- Default:
{} - Required:
false
svgsprite
A svg-sprite configuration.
verbose
Prints the plugin output to the console.
- Default:
false - Required:
false
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
- Filter By
- Group By
- Output Dimensions
- Skip Prefix
- Responsive Spritesheets
- Relative To Rule
- Webpack Hot Load
Contributing
Pull requests are welcome.
$ git clone git@github.com:2createStudio/postcss-sprites.git
$ npm install
$ npm run watch