CSS Sprite Helpers for Compass
These helpers make it easier to build and to work with css sprites.
While it is allowed to use these directly, to do so is considered "advanced usage". It is recommended that you instead use the css sprite mixins that are designed to work with these functions.
See the Spriting Tutorial for more information.
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.
$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
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
0px for spacing, and
Default values for all sprites can be specified by passing values for
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;
background: url('/images/icons.png?12345678') 0 -24px no-repeat;
$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
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
$icons: sprite-map("icons/*.png"); background-position: sprite-position($icons, new, 3px, -2px);
Would change the above output to:
background-position: 3px -36px;
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
background-position: sprite-position($icons, new, 0, 0, true);
Would result in something like:
background-position: 0 25%;