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;

Passing true for $use-percentages results in the background position being expressed in percentages instead of pixels. Example:

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

Returns the width of the generated sprite

Returns the height of the generated sprite

Returns the filesystem path of the generated sprite

Returns a list of all sprite names within the supplied map

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

Returns the path 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;

Passing true for the $use-percentages argument will return the sprite position in percentages instead of pixels. This is useful if you need to be able to scale the sprite up and down. Following the example above, this:

background-position: sprite-position($icons, new, 0, 0, true);

Would result in something like:

background-position: 0 25%;