npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

grunt-iconizr

v0.2.3

Published

Takes a folder of SVG images and creates a CSS icon kit out of them, serving the icons as SVG / PNG sprite or embedded data URIs (depending on the client's capabilities), along with suitable CSS / Sass / LESS / Stylus etc. resources and a JavaScript loade

Downloads

4

Readme

grunt-iconizr

Takes a folder of SVG images and creates a CSS icon kit out of them. Depending on the client's capabilities, icons are served as SVG / PNG sprite or embedded data URIs. iconizr creates suitable CSS / Sass / LESS etc. resources and a JavaScript loader for easy integration into your HTML documents.

The iconizr Grunt plugin wraps around the iconizr and svg-sprite Node.js modules.

Getting Started

This plugin requires Grunt ~0.4.2

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-iconizr --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-iconizr');

The "iconizr" task

Overview

In your project's Gruntfile, add a section named iconizr to the data object passed into grunt.initConfig().

grunt.initConfig({
  iconizr: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },
});

Of course, the top level options object is optional and you may define as many targets as you want. Your targets should look like this:

your_target: {
  src      : ['path/to/svg/image/dir'],  // Single input directory
  dest     : 'path/to/main/output/dir'   // Main output directory
}

As iconizr / svg-sprite accepts exactly one input directory for each run, only the first element of the src resource list will be used. That said, you may also provide a simple string as src argument:

your_target: {
  src      : 'path/to/svg/image/dir',    // Single input directory
  dest     : 'path/to/main/output/dir'   // Main output directory
}

Processing workflow

Each time you create a CSS icon kit, these are the processing stages:

  1. svg-sprite will find all SVG files inside the input directory and create an SVG sprite out of them.
    • The SVG images may be automatically optimized prior to being merged into the sprite, thus potentially saving some bytes.
    • When used from within iconizr, no output files (except the SVG sprite itself) will be produced at this stage.
  2. iconizr creates PNG fallbacks and accompanying stylesheet resources around the SVG files.
    • First, PNG versions of all SVG files will be created (including the SVG sprite).
    • The PNG images may be automatically optimized by tools like pngcrush, pngquant and optipng.
    • Depending on the configured output formats, iconizr creates stylesheet resources in several flavours (CSS, Sass, LESS etc.), each consisting of a set of files serving the icons in different ways (SVG or PNG, sprites or embedded data URIs).
    • An HTML loader fragment is created that has to be included into your HTML documents. It will take care of loading the stylesheet variant that is most appropriate for each client.
    • Optionally, a set of preview HTML documents is created that you can use for testing your icon kit.

Options

You may provide both task and target specific options:

your_target: {
  src       : 'path/to/svg/dir',
  dest      : 'path/to/css/dir',

  // Target specific options  
  options   : {
    dims    : true,
    keep    : true,
    preview : 'preview'
  }
}

Each option will either be used by svg-sprite or iconizr (or both) for configuring their processing workflows. Please see the corresponding references for details.

|Option |Description |Reference | |:------------|:------------|:-----------:| |render |Rendering configuration (output formats like CSS, Sass, LESS, HTML with inline SVG, etc.)|svg-sprite| |variables |Custom Mustache rendering variables [{}]|svg-sprite| |spritedir |Sprite subdirectory name ["svg"]|svg-sprite| |sprite |Sprite file name ["sprite"]|svg-sprite| |prefix |CSS selector prefix ["svg"]|svg-sprite| |common |Common CSS selector for all images [empty]|svg-sprite| |maxwidth |Maximum single image width [1000]|svg-sprite| |maxheight |Maximum single image height [1000]|svg-sprite| |padding |Transparent padding around the single images (in pixel) [0]|svg-sprite| |layout |Image arrangement within the sprite ("vertical", "horizontal" or "diagonal") ["vertical"]|svg-sprite| |pseudo |Character sequence for denoting CSS pseudo classes ["~"]|svg-sprite| |dims |Render image dimensions as separate CSS rules [false]|svg-sprite| |keep |Keep intermediate SVG files (inside the sprite subdirectory) [false]|svg-sprite| |recursive |Recursive scan of the input directory for SVG files [false]|svg-sprite| |verbose | Output verbose progress information (0-3) [0]|svg-sprite| |cleanwith |Module to be used for SVG cleaning. Currently "scour" or "svgo" ["svgo"]|svg-sprite| |cleanconfig |Configuration options for the cleaning module [{}]|svg-sprite| |quantize |Whether to quantize the PNG images (convert to 8-bit) [false]|node-iconizr| |level |PNG image optimization level (0-11) [3]|node-iconizr| |embed |Embed path for the HTML loader fragment [empty]|node-iconizr| |svg |Maximum data URI size for SVG embedding [1048576]|node-iconizr| |png |Maximum data URI size for PNG embedding [32768]|node-iconizr| |preview |Relative directory path used for preview document rendering [empty]|node-iconizr|

Usage Examples

Basic example

In this very basic example, the default options are used to create SVG and PNG sprites along with suitable CSS stylesheet resources (the render.css option defaults to TRUE) and the HTML loader fragment:

grunt.initConfig({
  iconizr: {
    simple: {
      src: ['path/to/svg/dir'],
      dest: 'path/to/css'
    }
  }
})

These files are created at path/to:

`-- css
    |-- icons
    |   |-- icons.png
    |   `-- icons.svg
    |-- sprite-loader-fragment.html
    |-- sprite-png-data.css
    |-- sprite-png-sprite.css
    |-- sprite-svg-data.css
    `-- sprite-svg-sprite.css

Sass / LESS example

In this slightly more verbose example, custom options are used to disable CSS output and create Sass / LESS resources instead (render). CSS rules specifying the image dimensions will be added (dims) and the optimized, intermediate SVG and PNG images used for creating the sprites won't be discarded (keep). Additionally, a set of HTML preview documents will be rendered (preview). verbose prints some messages during the creation process.

grunt.initConfig({
  svgsprite       : {
    spriteSass    : {
      src         : ['path/to/svg/dir'],
      dest        : 'path/to/css',
      options     : {
        preview   : 'preview',
        dims      : true,
        keep      : true,
        render    : {
          css     : false,
          scss    : '../sass/_icons',
          less    : '../less/_icons'
        },
        verbose   : 1
      }
    }
  }
})

These files are created at path/to (when run with the example SVG images coming with iconizr):

|-- css
|   |-- icons
|   |   |-- icons.png
|   |   |-- icons.svg
|   |   |-- weather-clear-night.png
|   |   |-- weather-clear-night.svg
|   |   |-- weather-clear.png
|   |   |-- weather-clear.svg
|   |   |-- weather-few-clouds-night.png
|   |   |-- weather-few-clouds-night.svg
|   |   |-- weather-few-clouds.png
|   |   |-- weather-few-clouds.svg
|   |   |-- weather-overcast.png
|   |   |-- weather-overcast.svg
|   |   |-- weather-severe-alert.png
|   |   |-- weather-severe-alert.svg
|   |   |-- weather-showers-scattered.png
|   |   |-- weather-showers-scattered.svg
|   |   |-- weather-showers.png
|   |   |-- weather-showers.svg
|   |   |-- weather-snow.png
|   |   |-- weather-snow.svg
|   |   |-- weather-storm.png
|   |   |-- weather-storm.svg
|   |   |-- weather-storm~hover.png
|   |   |-- weather-storm~hover.svg
|   |   |-- weather-x-missing-dimensions.png
|   |   `-- weather-x-missing-dimensions.svg
|   |-- preview
|   |   |-- svg-png-data-preview.html
|   |   |-- svg-png-sprite-preview.html
|   |   |-- svg-preview.html
|   |   |-- svg-svg-data-preview.html
|   |   `-- svg-svg-sprite-preview.html
|   `-- svg-loader-fragment.html
|-- less
|   |-- _icons-png-data.less
|   |-- _icons-png-single.less
|   |-- _icons-png-sprite.less
|   |-- _icons-svg-data.less
|   |-- _icons-svg-single.less
|   `-- _icons-svg-sprite.less
`-- sass
    |-- _icons-png-data.scss
    |-- _icons-png-single.scss
    |-- _icons-png-sprite.scss
    |-- _icons-svg-data.scss
    |-- _icons-svg-single.scss
    `-- _icons-svg-sprite.scss

Please note that — although the keep option has been specified — the *-single.{scss|less} stylesheets (respectively their CSS products) will never be used by the loader fragment. Compared to sprites or data URIs, serving single images to your clients must be considered the worst solution of all (HTTP request overhead). The *-single* file flavours are only contained for the sake of completeness.

Custom output formats & inline SVG embedding

The output rendering of grunt-iconizr is based on Mustache templates, which enables full customization of the generated results. You can even introduce completely new output formats. For details please see the svg-sprite documentation.

Also, you may use grunt-iconizr to create an inline SVG sprite that can be embedded directly into your HTML documents. Please see the svg-sprite documentation for details.

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 and test your code using Grunt.

Other versions

Besides this Grunt plugin there are several different versions of iconizr:

  • The Node.js module underlying this Grunt plugin.
  • A PHP command line version (that in fact is the "original" one, but compared to the Node.js / Grunt branch it's a little outdated at the moment ...).
  • The online service at iconizr.com that's based on the aforementioned PHP version (you can use it for creating CSS icon kits without the need of a local installation).
  • Finally, Haithem Bel Haj published a Grunt plugin that's also based on the PHP version. I never tried this one myself, though.

Release History

v0.2.3

v0.2.2

v0.2.0

  • Compatibility release
  • Fixed bug with the SVG sprite not used by the Sass & LESS output types (#6)
  • Documentation corrections

v0.1.1

  • npm troubleshooting release

v0.1.0

  • Initial release

Legal

Copyright © 2014 Joschi Kuphal [email protected] / @jkphl

grunt-iconizr is licensed under the terms of the MIT license.

The contained example SVG icons are part of the Tango Icon Library and belong to the Public Domain.