README.md

Retinafy your website with Sass & Compass

hidpi() is a Sass mixin that seamlessly serves high resolution background images to high density (Retina-like) displays. It comes with a debug mode to test Retina graphics on a regular display.

Demonstration

How to Use It

1. Install with Bower: bower install sass-hidpi
   OR Download _hidpi.scss to your Sass project (preferably with Compass enabled).
2. Import the partial in your Sass files: @import 'path/to/hidpi';

Perfect, you can now use the mixin in your Sass project.

Passing Content to the Mixin

You can virtually pass anything to the mixin and it will be displayed on high density displays.

In this example, the border color of the #logo element is:

• blue on regular displays
• red on HiDPI (Retina-like) displays

#logo {
  background: url('../images/logo.png') no-repeat;
  border: 1px solid blue;

  @include hidpi {
    background-image: url('../images/logo_x2.png');
    background-size: 250px 188px;
    border-color: red;
  }
}

Compiles to:

#logo {
  background: url("../images/logo.png") no-repeat;
  border: 1px solid blue;
}
@media (-webkit-min-device-pixel-ratio: 1.3),
       (min-resolution: 124.8dpi),
       (min-resolution: 1.3dppx) {
  #logo {
    background-image: url("../images/logo_x2.png");
    background-size: 250px 188px;
    border-color: red;
  }
}

Image Only

When passing the name of an image as an argument, hidpi() serves the equivalent high-resolution image on high-definition displays.

Image files should be named as follows, placed in the images folder of your Compass project:

• image.png: default image
• image_x2.png: high-resolution image

#logo-auto {
  @include hidpi(logo);
}

Compiles to:

#logo-auto {
  background-image: url('../images/logo.png');
}
@media (-webkit-min-device-pixel-ratio: 1.3),
       (min-resolution: 124.8dpi),
       (min-resolution: 1.3dppx) {
  #logo-auto {
    background-image: url('../images/logo_x2.png');
    background-size: 250px 188px;
  }
}

Note: this feature requires Compass.

Debug Mode

You can force hidpi() to always serve high-resolution graphics and test the rendering on a standard, non-Retina display.

Set the $hidpi-debug variable to true:

#logo-auto-debug {
  $hidpi-debug: true; // Force high-resolution graphics on standard displays
  @include hidpi(logo);
}

Compiles to:

#logo-auto-debug {
  background-image: url('../images/logo_x2.png');
  background-size: 250px 188px;
}

It loads logo_x2.png by default (no @media queries).

Non-PNG images

hidpi(image) is looking by default for images/image.png.

If your image is a JPEG, for example image.jpg, you should specify it as a second argument:

#image-jpeg {
  @include hidpi(image, jpg);
}

Same story with a GIF:

#image-gif {
  @include hidpi(image, gif);
}

Requirements

• Sass ~> 3.2 (for manual @include hidpi {})
• Compass ~> 0.12.2 (for auto @include hidpi(image);)

Note: Compass is only needed when passing arguments to hidpi() instead of a content-block.

Also Read

• Easy retina-ready images using SCSS by Jason Z. of 37signals
• Retinafy your web sites and apps — ebook by Thomas Fuchs
• Cross Browser Retina/High Resolution Media Queries

More HiDPI examples and resources

• Gist: Magically retinafy your sprites with Compass and HiDPI
• Gist: Using Compass to generate normal and retina sprite maps
• Compass mixins for dealing with HDPI (a.k.a. Retina) sprites and images in your CSS by @pierreburel
• A mixin for creating retina sprites with hover & active states by @AdamBrodzinski
• Retina Sprites with Compass — Blog post