Spriteowl documentation

The Extension

This is what Spriteowl does for you: In just 4 quick'n'easy steps the extension automatically creates a sprite stylesheet + PNG file(s) directly from Photoshop!

  1. Syntax:

    Select the output syntax. We support CSS, LESS, SASS/SCSS and Stylus.

  2. Retina:

    Choose this option on and Spriteowl will automatically generate two PNG files. A 100% sized PNG (Retina) and an additional 50% downsized PNG and all the required media queries.

  3. Trim:

    Choose this option on and Spriteowl will trim the output PNG for you.

  4. Export:

    Click and choose the location where to save the sprite stylesheet + PNG file(s).

A simple walktrough

Got you intrigued? Perfect, because working with Spriteowl is super easy!

1.

Photoshop

Before exporting a sprite with Spriteowl, please place your elements and name your groups and layers.

Tip:
Spriteowl export each top level group as a separate sprite (sprite stylesheet + PNG).
Groups and layers should be named according to class names in HTML, since you will use them later in your stylesheets.

2.

Export

Now it's time to export your sprite!

Select a output "Syntax", choose "Retina" on to generate two PNG files in different sizes, decide whether you want to "Trim" the PNG or not, click "Export" and choose a destination folder.

After the export you'll find two type of files in your destination folder: the sprite stylesheet (CSS, LESS, SASS/SCSS or Stylus) and the PNG file(s). If you look into the sprite stylesheet you will see that Spriteowl exactly generated the classes and mixins depending on your syntax and according to the layer and group structure of your sprite Psd.

3.

How to use the exported files

Import your sprite stylsheet and PNG(s) into your project and place your sprite elements wherever you want.

We provide you mixins and extendable placeholders for the height, width and position of each element. For more information please scroll down to the generated sprite stylesheet section.

Here are two simple examples:
Example 1
Example 2 (hover)

Tip:
For more useful mixins check out the Cssowl mixin library. 

<div class="codeexample">

  <div class="example1">
    <div class="coffe"></div>
    Example 1
  </div>

  <div class="example2">
    <div class="pacman"></div>
    Example 2 (hover)
  </div>
<div/>

// override the image sources before the import
$example-sheet-image: url("example.png")
$example-sheet-image-2x: url("example@2x.png")

// import the example spritesheet
@import "example"

.codeexample
  .example1 > .coffee
    +example-coffee()
    // or: @extend %example-coffee

  .example2 > .pacman
    +example-pacman-up()
    // or: @extend %example-pacman-up

    &:hover
      +example-pacman-over-position()
      // or: @extend %example-pacman-over-position

// override the image sources before the import
$example-sheet-image: url("example.png");
$example-sheet-image-2x: url("example@2x.png");

// import the example spritesheet
@import "example";

.codeexample {
  .example1 > .coffee {
    @include example-coffee();
    // or: @extend %example-coffee;
  }

  .example2 > .pacman {
    @include example-pacman-up();
    // or: @extend %example-pacman-up;

    &:hover {
      @include example-pacman-over-position();
      // or: @extend %example-pacman-over-position;
    }
  }
}

// import the example spritesheet
@import "example";

// override the image sources after the import
@example-sheet-image: url("example.png");
@example-sheet-image-2x: url("example@2x.png");

.codeexample {

  .example1 > .coffee {
    .example-coffee();
  }

  .example2 > .pacman {
    .example-pacman-up();

    &:hover {
      .example-pacman-over-position();
    }
  }
}

// override the image sources before the import
$example-sheet-image: url("example.png")
$example-sheet-image-2x: url("example@2x.png")

// import the example spritesheet
@import "example"

.codeexample

  .example1 > .coffee
      example-coffee()
      // or: @extend $example-coffee

  .example2 > .pacman
      example-pacman-up()
      // or: @extend $example-pacman-up

      &:hover
        example-pacman-over-position()
        // or: @extend $example-pacman-over-position

The generated sprite stylesheet

The generated sprite stylesheet contains two code parts, the first part is for the sprite itself and the second part for the sprite elements

1.

The sprite itself

The first part of the generated sprite stylesheet contains variables, mixins and extendable placeholders for the sprite itself like the sprite width, height and the path to the sprite PNG files. 

// variables
$example-sheet-width: 50px !default
$example-sheet-height: 130px !default
$example-sheet-image: url("example.png") !default
$example-sheet-image-2x: url("example@2x.png") !default
$example-sheet: $example-sheet-width $example-sheet-height $example-sheet-image $example-sheet-image-2x example !default

// mixins & extenable placeholders
=example-element()
  background-image: $example-sheet-image
  background-repeat: no-repeat
  @media only screen and (min--moz-device-pixel-ratio: 1.5), (-o-min-device-pixel-ratio: 3/2), (-webkit-min-device-pixel-ratio: 1.5), (min-device-pixel-ratio: 1.5), (min-resolution: 144dpi), (min-resolution: 1.5dppx)
    background-image: $example-sheet-image-2x
    background-size: $example-sheet-width $example-sheet-height
%example-element
  +example-element()

// variables
$example-sheet-width: 50px !default;
$example-sheet-height: 130px !default;
$example-sheet-image: url("example.png") !default;
$example-sheet-image-2x: url("example@2x.png") !default;
$example-sheet: $example-sheet-width $example-sheet-height $example-sheet-image $example-sheet-image-2x example !default;

// mixins & extenable placeholders
@mixin example-element() {
  background-image: $example-sheet-image;
  background-repeat: no-repeat;
  @media only screen and (min--moz-device-pixel-ratio: 1.5), (-o-min-device-pixel-ratio: 3/2), (-webkit-min-device-pixel-ratio: 1.5), (min-device-pixel-ratio: 1.5), (min-resolution: 144dpi), (min-resolution: 1.5dppx) {
    background-image: $example-sheet-image-2x;
    background-size: $example-sheet-width $example-sheet-height;
  }
}
%example-element {
  @include example-element();
}

// variables
@example-sheet-width: 50px;
@example-sheet-height: 130px;
@example-sheet-image: url("example.png");
@example-sheet-image-2x: url("example@2x.png");
@example-sheet: @example-sheet-width @example-sheet-height @example-sheet-image @example-sheet-image-2x example;

// mixins & extenable placeholders
.example-element() {
  background-image: @example-sheet-image;
  background-repeat: no-repeat;
  @media only screen and (min--moz-device-pixel-ratio: 1.5), (-o-min-device-pixel-ratio: 3/2), (-webkit-min-device-pixel-ratio: 1.5), (min-device-pixel-ratio: 1.5), (min-resolution: 144dpi), (min-resolution: 1.5dppx) {
    background-image: @example-sheet-image-2x;
    background-size: @example-sheet-width @example-sheet-height;
  }
}
.example-element {
  .example-element();
}

// variables
$example-sheet-width ?= 50px
$example-sheet-height ?= 130px
$example-sheet-image ?= url("example.png")
$example-sheet-image-2x ?= url("example@2x.png")
$example-sheet ?= $example-sheet-width $example-sheet-height $example-sheet-image-2x $example-sheet-image-2x example

// mixins & extenable placeholders
$example-sheet-width ?= 50px
$example-sheet-height ?= 130px
$example-sheet-image ?= url("example.png")
$example-sheet-image-2x ?= url("example@2x.png")
$example-sheet ?= $example-sheet-width $example-sheet-height $example-sheet-image-2x $example-sheet-image-2x example

example-element()
  background-image: $example-sheet-image
  background-repeat: no-repeat
  @media only screen and (min--moz-device-pixel-ratio: 1.5), (-o-min-device-pixel-ratio: 3/2), (-webkit-min-device-pixel-ratio: 1.5), (min-device-pixel-ratio: 1.5), (min-resolution: 144dpi), (min-resolution: 1.5dppx)
    background-image: $example-sheet-image-2x
    background-size: $example-sheet-width $example-sheet-height
$example-element
  sprite-element()
2.

The sprite elements

The second part contains the variables, mixins and extendable placeholders for each sprite element. The width() and height() sets the width or height of an element, sizes() sets both the width and height and the position() sets the x and y coordinates of an element. For more useful mixins check out the Cssowl mixin library. 

// variables
$example-coffee-x: -12px !default
$example-coffee-y: -11px !default
$example-coffee-width: 30px !default
$example-coffee-height: 19px !default
$example-coffee: $example-coffee-x $example-coffee-y $example-coffee-width $example-coffee-height example-coffee !default

// mixins & extenable placeholders
=example-coffee-width()
  width: $example-coffee-width
%example-coffee-width
  +example-coffee-width()
=example-coffee-height()
  height: $example-coffee-height
%example-coffee-height
  +example-coffee-height()
=example-coffee-size()
  +example-coffee-width()
  +example-coffee-height()
%example-coffee-size
  +example-coffee-size()
=example-coffee-position()
  background-position: $example-coffee-x $example-coffee-y
%example-coffee-position
  +example-coffee-position()
=example-coffee()
  +example-coffee-size()
  +example-coffee-position()
  @extend %example-element
%example-coffee
  +example-coffee()

// ...

// variables
$example-coffee-x: -12px !default;
$example-coffee-y: -11px !default;
$example-coffee-width: 30px !default;
$example-coffee-height: 19px !default;
$example-coffee: $example-coffee-x $example-coffee-y $example-coffee-width $example-coffee-height example-coffee !default;

// mixins & extenable placeholders
@mixin example-coffee-width() {
  width: $example-coffee-width;
}
%example-coffee-width {
  @include example-coffee-width();
}
@mixin example-coffee-height() {
  height: $example-coffee-height;
}
%example-coffee-height {
  @include example-coffee-height();
}
@mixin example-coffee-size() {
  @include example-coffee-width();
  @include example-coffee-height();
}
%example-coffee-size {
  @include example-coffee-size();
}
@mixin example-coffee-position() {
  background-position: $example-coffee-x $example-coffee-y;
}
%example-coffee-position {
  @include example-coffee-position();
}
@mixin example-coffee() {
  @include example-coffee-size();
  @include example-coffee-position();
  @extend %example-element;
}
%example-coffee {
  @include example-coffee();
}

// ...

// variables
@example-coffee-x: -12px;
@example-coffee-y: -11px;
@example-coffee-width: 30px;
@example-coffee-height: 19px;
@example-coffee: @example-coffee-x @example-coffee-y @example-coffee-width @example-coffee-height example-coffee;

// mixins
// note: as LESS doesn't support extendable placeholders (yet),
// we omit these in order to prevent unneeded code inclusion
.example-coffee-width() {
  width: @example-coffee-width;
}
.example-coffee-height() {
  height: @example-coffee-height;
}
.example-coffee-size() {
  .example-coffee-width();
  .example-coffee-height();
}
.example-coffee-position() {
  background-position: @example-coffee-x @example-coffee-y;
}
.example-coffee() {
  .example-coffee-size();
  .example-coffee-position();
  &:extend(.example-element);
}
.less-sprite-element(example-coffee) {
  .example-coffee-size();
  .example-coffee-position();
  &:extend(.example-element);
}

// ...

// variables
$example-coffee-x ?= -12px
$example-coffee-y ?= -11px
$example-coffee-width ?= 30px
$example-coffee-height ?= 19px
$example-coffee ?= $example-coffee-x $example-coffee-y $example-coffee-width $example-coffee-height example-coffee

// mixins & extenable placeholders
example-coffee-width()
  width: $example-coffee-width
$example-coffee-width
  example-coffee-width()
example-coffee-height()
  height: $example-coffee-height
$example-coffee-height
  example-coffee-height()
example-coffee-size()
  example-coffee-width()
  example-coffee-height()
$example-coffee-size
  example-coffee-size()
example-coffee-position()
  background-position: $example-coffee-x $example-coffee-y
$example-coffee-position
  example-coffee-position()
example-coffee()
  example-coffee-size()
  example-coffee-position()
  @extend $example-element
$example-coffee
  example-coffee()

// ...