--- 
title: CSS Sprite Helpers for Compass
crumb: Sprites
framework: compass
meta_description: Helper functions for working with CSS Sprite images.
layout: core
classnames:
  - reference
  - core
  - helpers
documented_functions:
  - "sprite-map"
  - "sprite"
  - "sprite-map-name"
  - "sprite-file"
  - "sprite-url"
  - "sprite-position"
  - "sprite-height"
  - "sprite-width"
  - "sprite-path"
  - "sprite-names"
---
%h1 <strong>CSS Sprite</strong> Helpers for Compass

:markdown
  These helpers make it easier to build and to work with <em>css sprites</em>.
  
  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](/help/tutorials/spriting/) for more information.

#sprite-map.helper
  %h3
    %a(href="#sprite-map")
      sprite-map(<span class="arg">$glob</span>, <span class="arg">...</span>)
  .details
    :markdown
      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`.

#sprite.helper
  %h3
    %a(href="#sprite")
      sprite(<span class="arg">$map</span>, <span class="arg">$sprite</span>, <span class="arg" data-default-value="0">$offset-x</span>, <span class="arg" data-default-value="0">$offset-y</span>, <span class="arg" data-default-value="false">$use-percentages</span>)
  .details
    :markdown
      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;

#sprite-width.helper
  %h3
    %a(href="#sprite-width")
      sprite-width(<span class="arg">$map</span>)
  .details
    :markdown
      Returns the width of the generated sprite

#sprite-height.helper
  %h3
    %a(href="#sprite-height")
      sprite-height(<span class="arg">$map</span>)
  .details
    :markdown
      Returns the height of the generated sprite

#sprite-path.helper
  %h3(href="#sprite-path")
    sprite-path(<span class="arg">$map</span>)
  .details
    :markdown
      Returns the filesystem path of the generated sprite

#sprite-names.helper
  %h3(href="#sprite-names")
    sprite-names(<span class="arg">$map</span>)
  .details
    :markdown
      Returns a list of all sprite names within the supplied map

#sprite-map-name.helper
  %h3
    %a(href="#sprite-map-name")
      sprite-map-name(<span class="arg">$map</span>)
  .details
    :markdown
      Returns the name of a css sprite map
      The name is derived from the folder than contains the css sprites.

#sprite-file.helper
  %h3
    %a(href="#sprite-file")
      sprite-file(<span class="arg">$map</span>, <span class="arg">$sprite</span>)
  .details
    :markdown
      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.

#sprite-url.helper
  %h3
    %a(href="#sprite-url")
      sprite-url(<span class="arg">$map</span>)
  .details
    :markdown
      Returns a url to the sprite image.

#sprite-position.helper
  %h3
    %a(href="#sprite-position")
      sprite-position(<span class="arg">$map</span>, <span class="arg">$sprite</span>, <span class="arg" data-default-value="0">$offset-x</span>, <span class="arg" data-default-value="0">$offset-y</span>, <span class="arg" data-default-value="false">$use-percentages</span>)
  .details
    :markdown
      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%;
