Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Sass sprite generation with compass for retina and non-retina images (example code for a Rails 3 application).


The below Sass+Compass/Ruby can be used to:

  • Generate retina and non-retina sprite maps
  • Allow a single style class to provide retina and non-retina support, per image
  • Automatically generate those sprite style classes

Example markup for a retina supported menu button:


To do this, we need:

  • 1x and 2x Sprite images
  • Sass to generate the sprite maps and styles
  • A custom sass function to help dynamically set the background-width of the 2x styles

1x and 2x Sprite images

Place sprite images in .../icon and .../icon2x directories.

  • 2x image widths must be of an even number of pixels
  • Every 2x image must have a corresponding 1x image (with the same name) and vice-versa

Sass, using compass to generate the sprite maps and styles

// Using Compass spriting, see
// Compass is generating the sprite map and styles from images in /app/assets/images/web/mobile/icon[2x]/*.png.
// NOTE: 2x icons must be an even number of pixels wide to avoid clipping/bleed.
// NOTE: Adding an icon will cause the sprites to be regenerated.

// Reduce sprite-map waste for variable-width icons
$icon-layout: horizontal
$icon2x-layout: horizontal

// Include dimensions for span background-image support
$icon-sprite-dimensions: true

// Ensure no overlap between sprites in the map
$icon-spacing: 6px
$icon2x-spacing: 12px

// Create 1x and 2x sprite map images
@import "web/mobile/icon/*.png"
@import "web/mobile/icon2x/*.png"

// Use 1x sprite for non-high-dpi screens
@include all-icon-sprites

// Override the sprite image for high-dpi screens
// and adjust background-size so 1x positions will work correctly
// for all 1x sprite style classes
@media (min--moz-device-pixel-ratio: 1.3),(-o-min-device-pixel-ratio: 2.6/2),(-webkit-min-device-pixel-ratio: 1.3),(min-device-pixel-ratio: 1.3),(min-resolution: 1.3dppx)
    background-image: $icon2x-sprites
    background-size: image-width(asset_path((sprite-url($icon-sprites)))) image-height(asset_path((sprite-url($icon-sprites))))

Custom Sass function

# /lib/assets/sass_functions.rb

module Sass::Script::Functions
  # return asset path given a url
  def asset_path(url)
    assert_type url, :String
      relative_path = url.value.match(/url\(.*\/assets\/(.*)\)/)[1]
    rescue StandardError
      raise "Didn't know how to find relative asset match for #{url.value}"

    file = "#{Compass.configuration.images_path}/#{relative_path}"
    unless File.exist?(file)
      # for asset precompilation
      file = "#{Rails.root}/public/assets/#{relative_path}"
  declare :asset_path, :args => [:url]

Rails with asset precompilation

We must require the library file explicitly

# /config/initializers/assets/sass_functions.rb

if defined?(Sass)
  require File.expand_path("./lib/assets/sass_functions.rb")

We also must require initializers explicitly during asset initialization (e.g. precompilation)

# config/applciation.rb

module AssetsInitializers
  class Railtie < Rails::Railtie
    initializer "assets_initializers.initialize_rails", group: :assets do |app|
      Dir["#{Rails.root}/config/initializers/assets/*.rb"].each{ |file| require file }
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.