CSS Sprite Helpers for Compass

Generates a css sprite map from the files matching the glob pattern. Uses the keyword-style arguments passed in to control the placement.

Only PNG files can be made into css sprites at this time.

The $glob should be glob pattern relative to the images directory that specifies what files will be in the css sprite. For example:

$icons: sprite-map("icons/*.png");
background: $icons;

This will generate a css sprite map and return a reference to it. It's important to capture this to a variable, because you will need to use it later when creating css sprites. In the above example you might end up with a new file named images/sprites/icons-a2ef041.png and your css stylesheet will have:

background: url('/images/sprites/icons-a2ef041.png?1234678') no-repeat;

The exact image name is not something you should depend on as it may change based on the arguments you pass in. Instead, you can use the sprite-url() function to create a reference to the css sprite map without generating the image again. Alternatively, simply using the sprite map variable in an property will have the same effect as calling sprite-url().

For each sprite in the css sprite map you can control the position, spacing, and whether or not it repeats. You do this by passing arguments to this function that tell each sprite how to behave. For instance if there is a icons/new.png then you can control it like so:

$icon-sprite: sprite-map("icons/*.png",
                $new-position: 100%, $new-spacing: 15px, $new-repeat: no-repeat);

If you don't specify these options they will default to 0% for position, 0px for spacing, and no-repeat for repeat.

Default values for all sprites can be specified by passing values for $position, $spacing, and $repeat.

Returns the image and background position for use in a single shorthand property:

$icons: sprite-map("icons/*.png"); // contains icons/new.png among others.
background: sprite($icons, new) no-repeat;

Becomes:

background: url('/images/icons.png?12345678') 0 -24px no-repeat;

Returns the name of a css sprite map The name is derived from the folder than contains the css sprites.

Returns the relative path (from the images directory) to the original file used when construction the sprite. This is suitable for passing to the image-width and image-height helpers.

Returns a url to the sprite image.

Returns the position for the original image in the sprite. This is suitable for use as a value to background-position:

$icons: sprite-map("icons/*.png");
background-position: sprite-position($icons, new);

Might generate something like:

background-position: 0 -34px;

You can adjust the background relative to this position by passing values for $offset-x and $offset-y:

$icons: sprite-map("icons/*.png");
background-position: sprite-position($icons, new, 3px, -2px);

Would change the above output to:

background-position: 3px -36px;