Getting started with Compass Spriting

One of the things that I struggle with on a new project or optimizing an older project is getting Compass spriting setup. I never remember the right syntax to use, or the proper functions to get everything setup and functioning. I typically try to go to the Compass Docs, but they aren't exactly straight forward in what you need to do.

So to help mitigate that struggle I'm going to list out the basic steps that I take when I start to use compass spriting. Hopefully it will help someone else, or at least serve as reference for your setup.

  1. Create a folder to source the images out of. - Typically I would create a subfolder of your images folder, or maybe even a sibling folder to your images folder. The sibling folder allows you some separation of concerns, as you probably don't want to upload files to the server that you aren't actually going to us.

  2. Add png's to the folder - Place the *.png files you want in the folder created in the first step.

  3. Verify your generated_images_dir - Verify your config.rb file has a generated_images_dir path configured to the location you want to build the images to.

  4. Verify your http_generated_images_path - If you are serving your images from a different path than the generated_images_dir you will need to set the http_generated_images_path. We use it because we are mapping the built location to a different path. You can put full urls or relative paths to the files. It's going to be used to generate the paths that are used into the CSS files.

  5. Import Compass Spriting - If you've not imported the compass mixins into your project you will need to do that.

    //to include just the spriting mixins
    @import "compass/utilities/sprites/base"; 
    //to include all the mixins
    @import "compass"; 
  6. Import the images - You are going to need to tell Compass what files to use. There are a couple of different ways to do this.

    1. Magic Imports - Basically compass iterates through the images in a defined path and automatically generates CSS for them. It uses the path and file names to generated out CSS classes for the images in the folder. This is a use case is for simple usage of spriting.

      @import "my-buttons/*.png";

      You can read more about that in the Compass Magic Selectors Tutorial. I won't discuss their usage in this article.

    2. Sprite-Maps - This is the method that I prefer to use, because it only generates the CSS you tell it to. Basically, you make the sprite-map, and tell it where to get the files. The sprite-map is the reference you use to tell Compass what sprite to use.

      $view-sprite: sprite-map("my-buttons/*.png");

      I like to define the variable name to a common name, so when I reuse a partial I don't have to keep up with the different sprite-map names.

  7. Use the Compass Helpers and Mixins - Compass provides several mixins to get the information you need for height, width, sprite-file, etc.

    1. sprite helper - You use the sprite helper to set the background position of the sprite.

      background: sprite($view-sprite, Green_Button) no-repeat;

      Would generated out something like:

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

      Notice that the name of the File is passed as a parameter to sprite, this tells Compass what image to use.

    2. sprite-dimensions mixin - This is going to give you the height and width of the image within the sprite. This allows you set elements to be the same size as the original image.

      @include sprite-dimensions($view-sprite, Green_Button);

      Would generated out something like:

      height: 30px;
      width: 60px;

      Again note that the image name is passed as a parameter to get the information from.

    3. image-height or image-width mixins - some of the normal image helpers can be used to get specific information from the sprited image.

      padding-top: image-height( sprite-file( $view-sprite, Green_Button ));
      padding-left: image-width( sprite-file( $view-sprite, Green_Button ));
    4. Configurations - sometimes you are going to need to adjust some default spriting settings. Spacing is the most common one. Sub-pixel rendering issues are the typical culprit here. In this example we are putting 3px spacing between all the images

      $view-sprite: sprite-map("my-buttons/*.png", $spacing: 3px);
  8. Example Sass file
@import "compass/utilities/sprites/base";
$view-sprite: sprite-map("my-buttons/*.png", $spacing: 3px);

.click-me {
    background: sprite($view-sprite, Green_Button) no-repeat;
    @include sprite-dimensions($view-sprite, Green_Button);
    padding-left: image-width( sprite-file( $view-sprite, Green_Button ));

Hopefully this will help you out as much as it does me.

Ray Pierce

Web Developer, RetailMeNot, Mentor, NodeBot builder, Texan

Austin, TX Ya'll
comments powered by Disqus