Builds CSS sprites and corresponding CSS from a directory of image files.
CoffeeScript CSS
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Magic Sprites

Build and customize css sprite sheets from a directory of images.

Magic Sprites relies on node-canvas, Installation instructions for your system can be found here Node-Canvas
Magic Sprites contains all of @danleech Simple-Icons using the 48px versions by default. Incidentally this is what prompted this project, me trying to sensibly convert his images into a spritesheet.


$ bower install MagicSprites
$ cd bower_components/MagicSprites
$ npm install

Basic Workflow

# ./your/project/bower_components/MagicSprites
$ gulp build #your compiled css will be in ./assets/css/magic.min.css

# or...

$ gulp watch 
# Will do all of the same stuff as gulp build
# Plus launch a preview server at http://localhost:9000. 
# It reloads on any changes to ./data/simple-icons.json or any additions 
# to ./images/icons_white/48px/

This will build a spritesheet and associated CSS file from simple-icons ./images/icons_white/48px The background-color data for this build can be found at ./data/simple-icons.json

Advanced workflow - building from your own images.

See note at bottom about developing inside bower_components (ie: don't)

Put images in ./images/my-images -> edit ./config.yaml -> gulp build / gulp watch

./config.yaml needs to contain

projectRoot: "./"

iconImagePath: "images/icons_white/48px/"

iconDataPath: "data/simple-icons.json"

iconSplitOnChar: "-"

outputImageDirectory: "assets/images/"

cssOutputDirectory: "assets/css/"

cssFileName: "magic"
  • iconImagePath - Path to your images, relative to projectRoot. No beginning /
  • iconDataPath - Relative path to the image data file. (this will be generated for you with "gulp build")
  • iconSplitOnChar - this is only needed for files appended with -32, -64, -some-junk, it will remove everything after the "-" when it generates classnames. Set to "iconSplitOnChar: false" without quotes if your images do not have annotations.
  • outPutImageDirectory - By default Magic Sprites encodes the png spritesheet as Base64 and includes it inside the resulting CSS file. This saves a request against your server. Changing this setting does nothing, without changing a setting in
  • cssOutputDirectory - Where do you want the CSS file to be output, relative to projectRoot.
  • cssFileName - The name of the final CSS file to be output.

If you have transparent background images, and wish to assign a CSS color to them, simply add the hex color code (with or without the #) to the "hex": field in my-imagedata.json.

Preview server

$ gulp watch

Fires up an express server bound to (http://localhost:9000 or http://internal.server:9000 if you are like me and work on a VM)

Css will be rebuilt on addition of images and changes to ./data/my-imagedata.json (or wherever they are set to), and will be auto-refreshed on your browser.

A note on Bower and bower_components

For the sake of development, all of the built files stay relative to the bower directory. This is probably not good practise, if you value your data. In a real installation you most likely want to use paths outside the MagicSprites directory.

./config.yaml needs to contain

projectRoot: "absolute/path/to/project"

iconImagePath: "images/icons_white/48px/"

iconDataPath: "data/simple-icons.json"

iconSplitOnChar: "-"

outPutImageDirectory: "assets/images/"

cssOutputDirectory: "assets/css/"

cssFileName: "magic"

Additional caveats

This is a beta project, running on a beta build tool, running on a beta platform, and it manipulates files. It doesnt delete anything, simply overwrites files that match. So please dont post an issue here if you named your data file /etc/shadow and are wondering what went wrong.

If you have any other issues, suggestions or improvements feel free to submit an issue or a PR.