sprite-css v1.0.2

sprite-css

This is a fork of http://github.com/selaux/node-sprite-generator, with trimmed features for reducing the installation noise and simplifying the usage.

Generates image sprites and their stylesheets from sets of images. Supports retina sprites.

The following features have been removed from the original implementation:

• Canvas and Graphics Magic compositors are removed. It uses only the jimp image compositor.
• Express and Grunt support is removed. Only standalone usage is allowed.
• Stylus, SASS and LESS stylesheets are not supported. Only prefixed CSS is allowed.
• All testing artifacts have been removed.
• All lint artifacts have been removed.
• Horizontal, vertical and diagonal layouts are removed. Only 'packed' mode is enabled.

Installation from npm

npm install sprite-css

Depending on your purposes, it may be needed an argument like --save, --save-dev or --global

Usage

var sprite = require('sprite-css');

sprite({
    src: [ 'images/sprite/*.png' ],
    spritePath: 'images/sprite.png',
    stylesheetPath: 'styles/sprite.css'
}, function (err) {
    console.log('Sprite generated!');
});

This will generate a sprite.png file and the corresponding CSS stylesheet.

Options

src

Type: String Default value: []
Specifies the images that will be combined to the sprite. Uses glob pattern matching, so paths with wildcards are valid as well.

spritePath

Type: String Default value: ''
The path your image sprite will be written to. The PNG format is the only one supported for the image sprite.

stylesheetPath

Type: String Default value: ''
The path the stylesheet will be written to.

stylesheetOptions

Type: Object Default value: '{}'
Options that will be passed on to the stylesheet generator. The built-in stylesheet generators support the following options:

• prefix (Type: String Default: 'prefix-'): A prefix that will be prepended to all classes/functions that are generated
• nameMapping (Type: Function Default: Filename): A function that specifies how filenames are mapped to class names in the stylesheet
• spritePath (Type: String Default: Relative Path): Defines which URL is used as the image path for the image sprite.
• pixelRatio (Type: Integer Default: 1): Specifies the pixelRatio for retina sprites.

layoutOptions

Type: Object Default value: {}
Options that will be passed on to the layout generation. The built-in layouter supports the following options:

• padding (Type: Integer Default: 0): Specifies the padding between the images in the layout.
• scaling (Type: Number Default: 1): Specifies the factor that the images are scaled with in the layout. This allows generating multiple, scaled versions of the same sprites using a single image set.

compositorOptions

Type: Object Default value: {}
Options that will be passed on to the compositor. The compositor supports the following options:

• compressionLevel (Type: Integer Default: 6): Specifies the compression level for the generated png file (compression levels range from 0-9).
• filter (Type: String Default: all): Specifies the filter used for the generated png file. Possible values: all, none, sub, up, average, paeth.

A more advanced example

var nsg = require('sprite-css');

nsg({
    src: [
        'public/images/sprite/*.png'
    ],
    spritePath: 'public/images/all-icons.png',
    stylesheetPath: 'public/stylesheets/all-icons.css',
    layoutOptions: {
        padding: 30
    },
    stylesheetOptions: {
        prefix: 'all-icons',
        spritePath: 'http://static.your-server.org/images/all-icons.png',
        pixelRatio: 2
    }
});

This will generate a retina-enabled sprite that can be accessed using classes like all-icons-home. The sprite will then be loaded from your static asset server.

License

MIT License