grunt-grunticon-pigment
Advanced tools
A collection of grunt tasks around filamentgroup's grunt-grunticon. Creates colourised versions of svg images.
A collection of grunt tasks around filamentgroup's grunt-grunticon. Creates colourised versions of svg images.
This plugin requires Grunt ~0.4.5
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-grunticon-pigment --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-grunticon-pigment');
In your project's Gruntfile, add a section named grunticon_pigment to the data object passed into grunt.initConfig().
grunt.initConfig({
grunticon_pigment: {
foo: {
files: [{
cwd: 'example/source',
dest: 'example/output'
}],
options: {
...
}
},
},
});
Type: String
Default value: "source"
The name of the folder containing the source svg files.
Type: String
Default value: "source-colourise"
The name of the folder containing the source svg files that get colourised. Please note, that the elements of the svg files must be within one grouped element at root level. Only shapes will be colourised, so make sure, that strokes are converted to shapes.
Type: Array
Default value: "source-colourise"
Defines the colour variations.
Type: String
Default value: "icons.data.svg.css"
The name of the generated CSS file containing SVG data uris.
Type: String
Default value: "icons.data.png.css"
The name of the generated CSS file containing PNG data uris.
Type: String
Default value: "icons.fallback.css"
The name of the generated CSS file containing external png url references.
Type: String
Default value: "icons.preview.html"
The name of the generated HTML preview file.
Type: String
Default value: "grunticon.loader.txt"
The name of the generated text file containing the grunticon loading snippet.
Type: String
Default value: "png"
The name of the generated folder containing the generated PNG images.
Type: String
Default value: value of options.pngfolder
Allows you to specify a custom URL to serve fallback PNGs at.
Example:
{
pngpath: "/assets/icons/png"
}
Will generate PNG fallbacks like:
.icon-bar {
background-image: url('/assets/icons/png/bar.png');
background-repeat: no-repeat;
}
Type: String
Default value: ".i-"
a string to prefix all css classes with.
Type: Object
Allows you to specify custom selectors (in addition to the generated cssprefix + filename - extension class) for individual files.
Example:
{
"foo": [".icon-bar", ".baz"]
}
will produce:
.icon-bar,
.bar,
.icon-foo {
//css
}
You can also use an asterisk in your custom selector!
Examples:
customselectors: {
"*": [".icon-$1:before", ".icon-$1-what", ".hey-$1"]
},
prefix: ".icon-"
Should give the file bear.svg the css
.icon-bear:before,
.icon-bear-what,
.hey-bear,
.icon-bear {
// CSS THINGS
}
And if there are files bear.svg and cat.svg, the css should be like:
.icon-bear:before,
.icon-bear-what,
.hey-bear,
.icon-bear {
// CSS THINGS
}
.icon-cat:before,
.icon-cat-what,
.hey-cat,
.icon-cat {
// CSS THINGS
}
This should give you more flexibility with your selectors.
Type: String
Default value: "32px"
a string that MUST be defined in px that will be the size of the PNG if there is no width given in the SVG element.
Type: String
Default value: "32px"
similar to defaultWidth, but for height
Type: String
Default value: Goes to the example/preview.hbs file
Takes a path to the template that will be used for the preview.html. Example of .hbs file contents:
<!doctype HTML>
<html>
<head>
<title>Icons Preview!</title>
<style>
body {
background-image: linear-gradient(#eee 25%, transparent 25%, transparent), linear-gradient(#eee 25%, transparent 25%, transparent), linear-gradient(transparent 75%, #eee 75%), linear-gradient(transparent 75%, #eee 75%);
width: 100%;
background-size: 10px 10px;
}
</style>
<script>
{{{loaderText}}}
grunticon(["icons.data.svg.css", "icons.data.png.css", "icons.fallback.css"]);
</script>
<noscript><link href="icons.fallback.css" rel="stylesheet"></noscript>
</head>
<body>
{{#each icons}}
{{#with this}}
<pre><code>{{prefix}}{{name}}:</code></pre><div class="{{prefixClass}}{{name}}" style="width: {{width}}px; height: {{height}}px;" ></div><hr/>
{{/with}}
{{/each}}
</body>
</html>
Type: String
Default value: "grunticon-tmp"
Let's you specify a tmp-folder. Useful when having multiple grunticon tasks and using grunt-concurrent.
Type: String
Default value: ""
Location of a handlebars template that will allow you to structure your CSS file the way that you choose. As more data becomes available via directory-encoder, more options will be available for you to tap into during templating.
Example of .hbs file contents:
{{#each customselectors}}{{this}},{{/each}}
{{prefix}}{{name}} {
background-image: url('{{datauri}}');
background-repeat: no-repeat;
}
Allows you to predefine colors as variables that can be used in filename color configuration.
grunt.initConfig({
grunticon_pigment: {
options: {
// CSS filenames
datasvgcss: "icons.data.svg.css",
datapngcss: "icons.data.png.css",
urlpngcss: "icons.fallback.css",
// preview HTML filename
previewhtml: "icons.preview.html",
// grunticon loader code snippet filename
loadersnippet: "grunticon.loader.js",
// folder name (within cwd) for svg files
svgFolder: "source",
svgColorFolder: "source-colourise",
// folder name (within dest) for png output
pngfolder: "png",
// prefix for CSS classnames
cssprefix: ".i-",
defaultWidth: "32px",
defaultHeight: "32px",
// colours for svg colourising
svgColors: ["#ffffff", "#ff0000"],
// css file path prefix - this defaults to "/" and will be placed before the "dest" path when stylesheets are loaded.
// This allows root-relative referencing of the CSS. If you don't want a prefix path, set to to ""
cssbasepath: "",
customselectors: {
"twitter": [".alternative-selector"]
},
// templates for css output and preview page
template: "template/default-css.hbs",
previewTemplate: "template/preview-custom.hbs"
},
files: [{
cwd: 'example/source',
dest: 'example/output'
}],
},
});
(Nothing yet)
/'
//
. //
|\//7
/' " \
. . .
| ( \
| '._ '
/ \'-'
grunticon is a Grunt.js task that makes it easy to manage icons and background images for all devices, preferring HD (retina) SVG icons but also provides fallback support for standard definition browsers, and old browsers alike. From a CSS perspective, it's easy to use, as it generates a class referencing each icon, and doesn't use CSS sprites.
grunticon takes a folder of SVG/PNG files (typically, icons that you've drawn in an application like Adobe Illustrator), and outputs them to CSS in 3 formats: svg data urls, png data urls, and a third fallback CSS file with references to regular png images, which are also automatically generated and placed in a folder.
grunticon also generates a small bit of JavaScript and CSS to drop into your site, which asynchronously loads the appropriate icon CSS depending on a browser's capabilities, and a preview HTML file with that loader script in place.
You can see a demonstration of the output here.
Grumpicon is a browser-based app that performs much of the functionality of Grunticon through a simple drag and drop interface. It's much easier to set up than Grunticon, and sometimes, it's all you need (though it won't always be!)
If you're interested in trying out Grumpicon, you might be interested in this handy guide as well: Grumpicon Workflow
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-grunticon --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-grunticon');
grunticon has a files object that needs to be filled in order to run, this files object currently requires that a cwd, and a dest dir are placed, and therefore will blow up without it. This will be fixed to better fit the pattern set by Grunt for this.
These can be set in your Gruntfile.js config file. Grunticon is a multitask, making it easy to create as many export batches as you'd like. Just create one or more custom named objects within the grunticon object, and configure Grunticon options within it, like so:
grunticon: {
myIcons: {
files: [{
expand: true,
cwd: 'example/source',
src: ['*.svg', '*.png'],
dest: "example/output"
}],
options: {
}
}
}
IMPORTANT NOTE: grunticon will overwrite any files in the dest directory if they are of the same name as a file that grunticon needs to create. For easiest results, you can set dest to a folder that does not yet exist in your directory and grunticon will create that folder, or set it to an existing folder and be sure to configure grunticon to create file names that do not already exist in that folder.
With these configuration properties set, you can add grunticon to your default tasks list. That'll look something like this:
grunt.registerTask('default', ['jshint', 'qunit', 'concat', 'uglify', 'grunticon:myIcons']);
grunticon will now batch your icons whenever you run grunt.
Type: String
Default value: "icons.data.svg.css"
The name of the generated CSS file containing SVG data uris.
Type: String
Default value: "icons.data.png.css"
The name of the generated CSS file containing PNG data uris
Type: String
Default value: "icons.fallback.css"
The name of the generated CSS file containing external png url references.
Type: String
Default value: "preview.html"
The name of the generated HTML file containing PNG data uris.
Type: String
Default value: "grunticon.loader.txt"
The name of the generated text file containing the grunticon loading snippet.
Type: String
Default value: "png/"
The name of the generated folder containing the generated PNG images.
Type: String
Default value: value of options.pngfolder
Allows you to specify a custom URL to serve fallback PNGs at.
Example:
{
pngpath: "/assets/icons/png"
}
Will generate PNG fallbacks like:
.icon-bar {
background-image: url('/assets/icons/png/bar.png');
background-repeat: no-repeat;
}
Type: String
Default value: ".icon-"
a string to prefix all css classes with.
Type: Object
Allows you to specify custom selectors (in addition to the generated cssprefix + filename - extension class) for individual files.
Example:
{
"foo": [".icon-bar", ".baz"]
}
will produce:
.icon-bar,
.bar,
.icon-foo {
//css
}
You can also use an asterisk in your custom selector!
Examples:
customselectors: {
"*": [".icon-$1:before", ".icon-$1-what", ".hey-$1"]
},
prefix: ".icon-"
Should give the file bear.svg the css
.icon-bear:before,
.icon-bear-what,
.hey-bear,
.icon-bear {
// CSS THINGS
}
And if there are files bear.svg and cat.svg, the css should be like:
.icon-bear:before,
.icon-bear-what,
.hey-bear,
.icon-bear {
// CSS THINGS
}
.icon-cat:before,
.icon-cat-what,
.hey-cat,
.icon-cat {
// CSS THINGS
}
This should give you more flexibility with your selectors.
Type: String
Default value: "400px"
a string that MUST be defined in px that will be the size of the PNG if there is no width given in the SVG element.
Type: String
Default value: "300px"
similar to defaultWidth, but for height
Type: String
Default value: Goes to the example/preview.hbs file
Takes a path to the template that will be used for the preview.html. Example of .hbs file contents:
<!doctype HTML>
<html>
<head>
<title>Icons Preview!</title>
<style>
body {
background-image: linear-gradient(#eee 25%, transparent 25%, transparent), linear-gradient(#eee 25%, transparent 25%, transparent), linear-gradient(transparent 75%, #eee 75%), linear-gradient(transparent 75%, #eee 75%);
width: 100%;
background-size: 10px 10px;
}
</style>
<script>
{{{loaderText}}}
grunticon(["icons.data.svg.css", "icons.data.png.css", "icons.fallback.css"]);
</script>
<noscript><link href="icons.fallback.css" rel="stylesheet"></noscript>
</head>
<body>
{{#each icons}}
{{#with this}}
<pre><code>{{prefix}}{{name}}:</code></pre><div class="{{prefixClass}}{{name}}" style="width: {{width}}px; height: {{height}}px;" ></div><hr/>
{{/with}}
{{/each}}
</body>
</html>
Type: String
Default value: "grunticon-tmp"
Let's you specify a tmp-folder. Useful when having multiple grunticon tasks and using grunt-concurrent.
Type: String
Default value: ""
Location of a handlebars template that will allow you to structure your CSS file the way that you choose. As more data becomes available via directory-encoder, more options will be available for you to tap into during templating.
Example of .hbs file contents:
{{#each customselectors}}{{this}},{{/each}}
{{prefix}}{{name}} {
background-image: url('{{datauri}}');
background-repeat: no-repeat;
}
Allows you to predefine colors as variables that can be used in filename color configuration.
Grunticon allows you to output any icon in different colors simply by changing its filename to the following syntax: myfilename.colors-red-aa0000-gray.svg. In this example, any color names or hexidecimal values that follow colors- and are separated by a dash will be used to generate additional icons of that color. By default, each icon will be assigned a numbered class name for CSS use. You can improve the class naming conventions by defining color variables in your Gruntfile's colors option shown above. When defined, you can reference a color variable in place of a color in your file names, and the generated classes will use that variable name as well. See the Gruntfile.js's colors option and the sample bear svg for an example of color automation.
A note on filesize impact: Adding color variations of an icon involves creating duplicates of that icon's SVG source in the CSS, so unfortunately, each color variation will cause an increase in filesize. However, transferring CSS with gzip compression can negate much of this filesize increase, and we highly recommend always transferring with gzip. In testing, we found that creating a color variation of every icon in our example set increased overall size by 25%, rather than 100% as a raw text duplicate would increase. That said, size increases for non-SVG-supporting browsers will be more dramatic, as the fallback PNGs will not have the heavy transfer compression as SVG enjoys. We advise using this feature on a case-by-case basis to ensure overhead is kept to a minimum.
The generated asynchronous CSS loader script delivers an appropriate icon stylesheet depending on a device/browser's capabilities. Grunticon is supported in cases where icon fonts fail.
Browsers that render the SVG data url stylesheet:
Browsers that receive the PNG data url stylesheet:
Browsers that receive the fallback png request:
View the full support spreadsheet here. Feel free to edit it if you find anything new.
The test page can be found here.
In earlier versions of Grunticon, we included SVGO to optimize the SVG output. In the 1.0 version, we removed this dependency to ease the installation complexity but still recommend that SVG optimization is part of the Grunticon workflow.
When producing SVGs through a tool like Illustrator, there is a lot of unnecessary markup, comments, and general code written into your SVG files. Because of that, we strongly recommend using a tool like grunt-svgmin. If run before running Grunticon, it can greatly reduce your filesizes!
Here's an example:
svgmin: {
dist: {
files: [{
expand: true,
cwd: 'example/svgs',
src: ['*.svg'],
dest: 'example/source'
}]
}
},
grunticon: {
foo: {
files: [{
expand: true,
cwd: 'example/source',
src: ['*.svg', '*.png'],
dest: "example/output"
}],
options: {
}
}
}
For a more extensive example, check out our Gruntfile and example project.
One of the great benefits to data uris is the ability to compress the images heavily via gzip compression. Be sure to enable gzip of CSS on your server, as it'll cut your icon transfer size greatly.
The workflow we've been using so far involves creating a new Illustrator file with the artboard set to the desired size of the icon you want set in the CSS.
Export the artwork by choosing File > Save as... In the dialog, choose "SVG" as the format and enter a name for the file (this wil be used as your class name later, so keep it free of any disallowed CSS class characters like ., {, (, ), etc.
In the Save SVG dialog that opens up, there are lots of options. SVG has a ton of formats, so here are a few tips we've learned.
#, ., >, or any other css selecting character in their names, they will likely be improperly processed.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.
With the release of 1.0.0, we have broken out the code to make it easier to maintain so we can more quickly respond to bugs and new feature requests. There have also been some changes to the way the Gruntfile is set up, in that it now uses Grunt's file system.
Example:
Old way:
grunticon: {
foo: {
options: {
src: "example/source",
dest: "example/dest"
}
}
}
New way:
grunticon: {
foo: {
files: [{
expand: true,
cwd: 'example/source',
src: ['*.svg', '*.png'],
dest: "example/output"
}],
options: {
}
}
}
Custom Selectors now have a wildcard!
Example:
grunticon: {
foo: {
files: [{
expand: true,
cwd: 'example/source',
src: ['*.svg', '*.png'],
dest: "example/output"
}],
options: {
customselectors: {
"*": [".icon-$1:before"]
}
}
}
}
If you have a file named bear.svg and a file named cat.svg, it will produce these selectors:
.icon-bear:before,
.icon-bear{
//css
}
.icon-cat:before,
.icon-cat{
//css
}
We've parted with SVGO, as keeping grunt-svgmin part of your build process is easy and they do a great job on that project over there. We've also parted with using PNGCrush for the time being. We're currently looking for another solution (suggestions welcome).
pngpath optionpreviewTemplate optioncolors optionFAQs
A collection of grunt tasks around filamentgroup's grunt-grunticon. Creates colourised versions of SVG images.
The npm package grunt-grunticon-pigment receives a total of 0 weekly downloads. As such, grunt-grunticon-pigment popularity was classified as not popular.
We found that grunt-grunticon-pigment demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
pnpm 10 blocks lifecycle scripts by default to improve security, addressing supply chain attack risks but sparking debate over compatibility and workflow changes.
Product
Socket now supports uv.lock files to ensure consistent, secure dependency resolution for Python projects and enhance supply chain security.
Research
Security News
Socket researchers have discovered multiple malicious npm packages targeting Solana private keys, abusing Gmail to exfiltrate the data and drain Solana wallets.