Home

Awesome

spritesheet-templates CircleCI

Convert spritesheet data into CSS or CSS pre-processor data

spritesheet-templates, formerly json2css, was built as part of spritesmith, a tool that converts images into spritesheets and CSS variables.

Getting Started

Install the module with: npm install spritesheet-templates

// Compilation
var templater = require('spritesheet-templates');
templater({
  sprites: [{
    name: 'github', x: 0, y: 0, width: 10, height: 20
  }, {
    name: 'twitter', x: 10, y: 20, width: 20, height: 30
  }, {
    name: 'rss', x: 30, y: 50, width: 50, height: 50
  }],
  spritesheet: {
    width: 80, height: 100, image: 'url/path/to/spritesheet.png'
  }
}, {format: 'stylus'}); /*
// Result stylus
$github_x = 0px;
$github_y = 0px;
...
$github = 0px 0px 0px 0px 10px 20px 80px 100px 'url/path/to/spritesheet.png' 'github';
...
$twitter = 10px 20px -10px -20px 20px 30px 80px 100px 'url/path/to/spritesheet.png' 'twitter';
...
$rss = 30px 50px -30px -50px 50px 50px 80px 100px 'url/path/to/spritesheet.png' 'rss';
...
spriteWidth($sprite) {
  width: $sprite[0];
}
...
sprite($sprite) {
  spriteImage($sprite)
  spritePosition($sprite)
  spriteWidth($sprite)
  spriteHeight($sprite)
}

// Inside of your Stylus
.github-logo {
  sprite($github);
}
*/

Documentation

spritesheet-templates exports the function templater as its module.exports.

templater(data, options)

Converter for spritesheet/sprite info into spritesheet

Returns:

Retina parameters

retina templates require additional parameters data.retina_sprites, data.retina_spritesheet and data.retina_groups to be passed in.

For the variables to be useful, the retina spritesheet should be a 2x scale image of the original spritesheet. Similarly, retina sprites should be positioned in the same layout and order as their normal counterparts (e.g. [{x: 0, y: 0}, {x: 20, y: 20}] should correspond to [{x: 0, y: 0}, {x: 40, y: 40}]).

Templates

Below are our template options for options.format.

Handlebars-based templates support inheritance via handlebars-layouts (e.g. {{#extend "css"}}). Inherited templates must copy/paste JSON front matter. An example can be found in the Examples section.

Retina templates have the same setup but are located in the Retina templates section for convenience.

css

Ouput CSS variables as CSS rules.

Options:

Handlebars blocks:

css is a Handlebars based template. We allow for overriding the following sections:

Example:

.icon-sprite1 {
  background-image: url(nested/dir/spritesheet.png);
  background-position: 0px 0px;
  width: 10px;
  height: 20px;
}
.icon-sprite2 {
/* ... */

json

Output CSS variables in JSON format.

Example:

{
    "sprite1": {
        "x": 0,
        "y": 0,
        "width": 10,
        "height": 20,
        "total_width": 80,
        "total_height": 100,
        "image": "nested/dir/spritesheet.png",
        "offset_x": 0,
        "offset_y": 0,
        "px": {
            "x": "0px",
            "y": "0px",
            "offset_x": "0px",
            "offset_y": "0px",
            "height": "20px",
            "width": "10px",
            "total_height": "100px",
            "total_width": "80px"
        },
        "escaped_image": "nested/dir/spritesheet.png"
    },
    "sprite2": {
    // ...

json_array

Output CSS variables as an array of objects.

Example:

[
    {
        "name": "sprite1",
        "x": 0,
        "y": 0,
        "width": 10,
        "height": 20,
        "total_width": 80,
        "total_height": 100,
        "image": "nested/dir/spritesheet.png",
        "offset_x": 0,
        "offset_y": 0,
        "px": {
            "x": "0px",
            "y": "0px",
            "offset_x": "0px",
            "offset_y": "0px",
            "height": "20px",
            "width": "10px",
            "total_height": "100px",
            "total_width": "80px"
        },
        "escaped_image": "nested/dir/spritesheet.png"
    },
    {
        "name": "sprite2",
        // ...

json_texture

Output CSS variables as an object in format similar to that of TexturePacker. Useful for game frameworks, such as Phaser, Pixi.js, and others.

For consistency with TexturePacker, we will use the basename of a given image. spritesmith provides this via sprite.source_image. If you would like to provide a custom name, then please define sprite.frame_name:

// Input
{
  sprites: [{
    frame_name: 'hello', name: 'github', x: 0, y: 0, width: 10, height: 20
  }]
}

// Output
{
  frames: {
    hello: {x: 0, y: 0, w: 10, h: 20}
  }
}

If neither sprite.source_image nor spriteframe is used, then sprite.name will be used.

For integration in grunt-spritesmith/gulp.spritesmith, please see their cssVarMap documentation.

Example:

{
    "frames": {
        "mysprite.png": {
            "frame": {
                "x": 10,
                "y": 20,
                "w": 20,
                "h": 30
            }
        },
        // ...
    },
    "meta": {
        "app": "spritesheet-templates",
        // ...
        "image": "nested/dir/spritesheet.png",
        "scale": 1,
        "size": {
            "w": 80,
            "h": 100
        }
    }
}

less

Output CSS variables as LESS variables.

Options:

Handlebars blocks:

less is a Handlebars based template. We allow for overriding the following sections:

Example:

@sprite1-name: 'sprite1';
@sprite1-x: 0px;
@sprite1-y: 0px;
@sprite1-offset-x: 0px;
@sprite1-offset-y: 0px;
@sprite1-width: 10px;
@sprite1-height: 20px;
@sprite1-total-width: 80px;
@sprite1-total-height: 100px;
@sprite1-image: 'nested/dir/spritesheet.png';
@sprite1: 0px 0px 0px 0px 10px 20px 80px 100px 'nested/dir/spritesheet.png' 'sprite1';
@sprite2-name: 'sprite2';
// ...

sass

Output CSS variables as SASS variables.

Options:

Handlebars blocks:

sass is a Handlebars based template. We allow for overriding the following sections:

Example:

$sprite1-name: 'sprite1'
$sprite1-x: 0px
$sprite1-y: 0px
$sprite1-offset-x: 0px
$sprite1-offset-y: 0px
$sprite1-width: 10px
$sprite1-height: 20px
$sprite1-total-width: 80px
$sprite1-total-height: 100px
$sprite1-image: 'nested/dir/spritesheet.png'
$sprite1: 0px 0px 0px 0px 10px 20px 80px 100px 'nested/dir/spritesheet.png' 'sprite1'
$sprite2-name: 'sprite2'
// ...

scss

Output CSS variables as SCSS variables.

Options:

Handlebars blocks:

scss is a Handlebars based template. We allow for overriding the following sections:

Example:

$sprite1-name: 'sprite1';
$sprite1-x: 0px;
$sprite1-y: 0px;
$sprite1-offset-x: 0px;
$sprite1-offset-y: 0px;
$sprite1-width: 10px;
$sprite1-height: 20px;
$sprite1-total-width: 80px;
$sprite1-total-height: 100px;
$sprite1-image: 'nested/dir/spritesheet.png';
$sprite1: 0px 0px 0px 0px 10px 20px 80px 100px 'nested/dir/spritesheet.png' 'sprite1';
$sprite2-name: 'sprite2';
// ...

scss_maps

Output CSS variables as SCSS maps variables.

Options:

Handlebars blocks:

scss_maps is a Handlebars based template. We allow for overriding the following sections:

Example:

$sprite1: (
  name: 'sprite1',
  x: 0px,
  y: 0px,
  offset_x: 0px,
  offset_y: 0px,
  width: 10px,
  height: 20px,
  total_width: 80px,
  total_height: 100px,
  image: 'nested/dir/spritesheet.png'
);
$sprite2: (
// ...

stylus

Output CSS variables as Stylus variables.

Options:

Handlebars blocks:

stylus is a Handlebars based template. We allow for overriding the following sections:

Example:

$sprite1_name = 'sprite1';
$sprite1_x = 0px;
$sprite1_y = 0px;
$sprite1_offset_x = 0px;
$sprite1_offset_y = 0px;
$sprite1_width = 10px;
$sprite1_height = 20px;
$sprite1_total_width = 80px;
$sprite1_total_height = 100px;
$sprite1_image = 'nested/dir/spritesheet.png';
$sprite1 = 0px 0px 0px 0px 10px 20px 80px 100px 'nested/dir/spritesheet.png';
$sprite2_name = 'sprite2';
// ...

Retina templates

These are a subset of templates that support retina spritesheets. These require retina parameters like retina_sprites are provided in order to work properly.

css_retina

Ouput CSS variables as CSS rules with media query and additional rules for retina support.

Options:

Handlebars blocks:

We extend from the css template and have its blocks. There are no new sections for retina data.

Example:

.icon-sprite1 {
  background-image: url(nested/dir/spritesheet.png);
  background-position: 0px 0px;
  width: 10px;
  height: 20px;
}
/* ... */
@media (-webkit-min-device-pixel-ratio: 2),
       (min-resolution: 192dpi) {
  .icon-sprite1 {
    background-image: url(nested/dir/spritesheet@2x.png);
    background-size: 80px 100px;
  }
}

json_retina

Output retina CSS variables in JSON format.

Example:

{
    "sprite1": {
        "normal": {
            "x": 0,
            "y": 0,
            "width": 10,
            "height": 20,
            "image": "nested/dir/spritesheet.png",
            "escaped_image": "nested/dir/spritesheet.png",
            "total_width": 80,
            "total_height": 100,
            "offset_x": 0,
            "offset_y": 0,
            "px": {
                "x": "0px",
                "y": "0px",
                "offset_x": "0px",
                "offset_y": "0px",
                "height": "20px",
                "width": "10px",
                "total_height": "100px",
                "total_width": "80px"
            }
        },
        "retina": {
            "x": 0,
            "y": 0,
            // ...
    },
    "sprite2": {
    // ...

json_array_retina

Output retina CSS variables as an array of objects.

Example:

[
    {
        "name": "sprite1",
        "normal": {
            "x": 0,
            "y": 0,
            "width": 10,
            "height": 20,
            "total_width": 80,
            "total_height": 100,
            // ...
        },
        "retina": {
            "x": 0,
            "y": 0,
            "width": 20,
            "height": 40,
            "total_width": 160,
            "total_height": 200,
            // ...
        }
    },
    {
        "name": "sprite2",
        // ...

less_retina

Output retina CSS variables as LESS variables.

Options:

Handlebars blocks:

We extend from the less template and have its blocks. There are no new sections for retina data.

Example:

@sprite1-name: 'sprite1';
@sprite1-x: 0px;
@sprite1-y: 0px;
@sprite1-offset-x: 0px;
@sprite1-offset-y: 0px;
@sprite1-total-width: 80px;
@sprite1-total-height: 100px;
// ...
@sprite2-2x-total-width: 160px;
@sprite2-2x-total-height: 200px;
@sprite2-2x-image: 'nested/dir/spritesheet@2x.png';
@sprite2-2x: 0px 0px 0px 0px 20px 40px 160px 200px 'nested/dir/spritesheet@2x.png' 'sprite2@2x';
// ...
@sprite3-group: 'sprite3' @sprite3 @sprite3-2x;
@retina-groups: @sprite1-group @sprite2-group @sprite3-group;
// ...

sass_retina

Output retina CSS variables as SASS variables and mixins.

Options:

Handlebars blocks:

We extend from the sass template and have its blocks. There are no new sections for retina data.

Example:

$sprite1-name: 'sprite1'
$sprite1-x: 0px
$sprite1-y: 0px
$sprite1-offset-x: 0px
$sprite1-total-width: 80px
$sprite1-total-height: 100px
// ...
$sprite2-2x-total-width: 160px
$sprite2-2x-total-height: 200px
$sprite2-2x-image: 'nested/dir/spritesheet@2x.png'
$sprite2-2x: (20px, 40px, -20px, -40px, 40px, 60px, 160px, 200px, 'nested/dir/spritesheet@2x.png', 'sprite2@2x', )
// ...
$sprite3-group: ('sprite3', $sprite3, $sprite3-2x, )
$retina-groups: ($sprite1-group, $sprite2-group, $sprite3-group, )
// ...

scss_retina

Output retina CSS variables as SCSS variables and mixins.

Options:

Handlebars blocks:

We extend from the scss template and have its blocks. There are no new sections for retina data.

Example:

$sprite1-name: 'sprite1';
$sprite1-x: 0px;
$sprite1-y: 0px;
$sprite1-offset-x: 0px;
$sprite1-total-width: 80px;
$sprite1-total-height: 100px;
// ...
$sprite2-2x-total-width: 160px;
$sprite2-2x-total-height: 200px;
$sprite2-2x-image: 'nested/dir/spritesheet@2x.png';
$sprite2-2x: (20px, 40px, -20px, -40px, 40px, 60px, 160px, 200px, 'nested/dir/spritesheet@2x.png', 'sprite2@2x', );
// ...
$sprite3-group: ('sprite3', $sprite3, $sprite3-2x, );
$retina-groups: ($sprite1-group, $sprite2-group, $sprite3-group, );
// ...

scss_maps_retina

Output retina CSS variables as SCSS maps variables.

Options:

Handlebars blocks:

We extend from the scss_maps template and have its blocks. There are no new sections for retina data.

Example:

$sprite1: (
  name: 'sprite1',
  x: 0px,
  y: 0px,
  offset_x: 0px,
  offset_y: 0px,
  total_width: 80px,
  total_height: 100px,
  // ...
);
$sprite2: (
  // ...
  total-width: 160px,
  total-height: 200px,
  image: 'nested/dir/spritesheet@2x.png'
);
// ...
$sprite3-group: (
  name: 'sprite3',
  normal: $sprite3,
  retina: $sprite3-2x
);
$retina-groups: ($sprite1-group, $sprite2-group, $sprite3-group, );
// ...

stylus_retina

Output retina CSS variables as Stylus variables and mixins.

Options:

Handlebars blocks:

We extend from the stylus template and have its blocks. There are no new sections for retina data.

Example:

$sprite1_name = 'sprite1';
$sprite1_x = 0px;
$sprite1_y = 0px;
$sprite1_offset_x = 0px;
$sprite1_offset_y = 0px;
$sprite1_total_width = 80px;
$sprite1_total_height = 100px;
// ...
$sprite2_2x_total_width = 160px;
$sprite2_2x_total_height = 200px;
$sprite2_2x_image = 'nested/dir/spritesheet@2x.png';
$sprite2_2x = 20px 40px -20px -40px 40px 60px 160px 200px 'nested/dir/spritesheet@2x.png' 'sprite2@2x';
// ...
$sprite3_group = 'sprite3' $sprite3 $sprite3_2x;
$retina_groups = $sprite1_group $sprite2_group $sprite3_group;
// ...

Custom

Custom templates can be added dynamically via templater.addTemplate and templater.addHandlebarsTemplate.

Template data

The parameters passed into your template are known as data. These are a cloned copy of the data originally passed in. We add some normalized properties for your convenience.

Handlebars template data

We provide an extra set of data for handlebars templates for variable/string names.

Retina template data

These are additional properties of the template data when retina parameters have been passed in (e.g. retina_sprites, retina_groups). As with the normal data, it is cloned copy of the original data with additional properties for convenience.

Retina Handlebars template data

Retina specific properties will have the same corresponding new data for Handlebars templates

templater.addTemplate(name, fn)

Method to define a custom template under the format of name.

templater.addHandlebarsTemplate(name, tmplStr)

Method to define a custom handlebars template under the format of name.

As noted in the Templates section, these can inherit from existing templates via handlebars-layouts conventions (e.g. {{#extend "scss"}}). An example can be found in the Examples section.

templater.addMustacheTemplate(name, tmplStr)

Deprecated alias for templater.addHandlebarsTemplate

Examples

Retina configuration

In this example, we will process a template with retina data.

var templater = require('spritesheet-templates');
templater({
  sprites: [{
    name: 'github', x: 0, y: 0, width: 10, height: 20
  }, {
    name: 'twitter', x: 10, y: 20, width: 20, height: 30
  }, {
    name: 'rss', x: 30, y: 50, width: 50, height: 50
  }],
  // Note that the retina sprites are in the same order as `sprites`
  retina_sprites: [{
    name: 'github@2x', x: 0, y: 0, width: 20, height: 40
  }, {
    name: 'twitter@2x', x: 20, y: 40, width: 40, height: 60
  }, {
    name: 'rss@2x', x: 60, y: 100, width: 100, height: 100
  }],
  spritesheet: {
    width: 80, height: 100, image: 'url/path/to/spritesheet.png'
  },
  retina_spritesheet: {
    width: 160, height: 200, image: 'url/path/to/spritesheet@2x.png'
  },
  retina_groups: [{
    name: 'github', index: 0
  }, {
    name: 'twitter', index: 1
  }, {
    name: 'rss', index: 2
  }]
}, {format: 'scss_retina'}); /*
$github-name: 'github';
$github-x: 0px;
...
$twitter-2x-name: 'twitter@2x';
$twitter-2x-x: 20px;
...
$rss-group-name: 'rss';
$rss-group: ('rss', $rss, $rss-2x, );
$retina-groups: ($github-group, $twitter-group, $rss-group, );
*/

Inheriting from a template

In this example, we will extend the SCSS template to output a minimal set of template data.

It should be noted that we must include the JSON front matter from the original template we are inheriting from to preserve default casing and options.

scss-minimal.handlebars:

{
  // Default options
  'functions': true,
  'variableNameTransforms': ['dasherize']
}

{{#extend "scss"}}
{{#content "sprites"}}
{{#each sprites}}
${{strings.name}}: ({{px.x}}, {{px.y}}, {{px.offset_x}}, {{px.offset_y}}, {{px.width}}, {{px.height}}, {{px.total_width}}, {{px.total_height}}, '{{{escaped_image}}}', '{{name}}', );
{{/each}}
{{/content}}
{{#content "spritesheet"}}
${{spritesheet_info.strings.name_sprites}}: ({{#each sprites}}${{strings.name}}, {{/each}});
${{spritesheet_info.strings.name}}: ({{spritesheet.px.width}}, {{spritesheet.px.height}}, '{{{spritesheet.escaped_image}}}', ${{spritesheet_info.strings.name_sprites}}, );
{{/content}}
{{/extend}}

index.js:

// Load in our dependencies
var fs = require('fs');
var templater = require('spritesheet-templates');

// Register our new template
var scssMinimalHandlebars = fs.readFileSync('scss-minimal.handlebars', 'utf8');
templater.addHandlebarsTemplate('scss-minimal', scssMinimalHandlebars);

// Run our templater
templater({
  sprites: [{
    name: 'github', x: 0, y: 0, width: 10, height: 20
  }, {
    name: 'twitter', x: 10, y: 20, width: 20, height: 30
  }, {
    name: 'rss', x: 30, y: 50, width: 50, height: 50
  }],
  spritesheet: {
    width: 80, height: 100, image: 'url/path/to/spritesheet.png'
  }
}, {format: 'scss-minimal'}); /*
$github: (0px, 0px, 0px, 0px, 10px, 20px, 80px, 100px, 'url/path/to/spritesheet.png', 'github', );
$twitter: (10px, 20px, -10px, -20px, 20px, 30px, 80px, 100px, 'url/path/to/spritesheet.png', 'twitter', );
$rss: (30px, 50px, -30px, -50px, 50px, 50px, 80px, 100px, 'url/path/to/spritesheet.png', 'rss', );
$spritesheet-sprites: ($github, $twitter, $rss, );
$spritesheet: (80px, 100px, 'url/path/to/spritesheet.png', $spritesheet-sprites, );
*/

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via npm run lint and test via npm test.

Donating

Support this project and others by twolfson via donations.

http://twolfson.com/support-me

Unlicense

As of Sep 08 2013, Todd Wolfson has released this repository and its contents to the public domain.

It has been released under the UNLICENSE.

Prior to Sep 08 2013, this repository and its contents were licensed under the MIT license.