v0.4.3 — 2.9k min/gzipped

iconic.js

Included with every Iconic license, iconic.js is our front-end JavaScript library that enables many of Iconic's advanced features.


Key Functionality

  • Fast, caching, dynamic SVG injection, using our open source SVG Injector library.
  • Callback support for auto-injection and manual injection calls.
  • Responsive SVG stack style calculation and automatic fluid switching.
  • Smart Icon API JavaScript code linking and caching.
  • SVG positioning and alignment support.
  • PNG fallback support
  • Cross-browser normalization and polyfills to mitigate SVG inconsistencies and quirks.

Usage

To get started, include iconic.js on your page.

<script src="iconic.min.js"></script>

By doing that a few things happen automatically for you:

  • Any img tag with the iconic class and an SVG file src will be replaced with the full SVG markup inline. The async loaded SVG is also cached so multiple uses of an icon only requires one server request.

    Development tip: The dynamic injection process uses AJAX calls to load SVG. If you are developing locally without running a local webserver, be aware that default browser security settings may block these calls.

  • The JavaScript in any Smart Icons you use will be extracted, cached, initialized and connected to the icons making their APIs available for use.

  • A small CSS style tag shim is injected into the page's head that includes a few rules to support our responsive and sizing functionality.

Options

Optionally, there are a number of configuration setting you can make and callbacks you can hook.

  • autoInjectSelector - String

    The selector to use for auto-injecting SVGs during page load.

    Default: img.iconic

  • pngFallback - String

    The directory where fallback PNGs are located for use if the browser doesn't support SVG. This will look for a file with a .png extension matching the SVG filename defined in the src (or data-src).

    For additional flexibility, per-element fallbacks are also available.

  • each - function

    Callback for each injection that iconic.js does, including manual and auto-injection.

  • autoInjectDone - function

    Callback called when auto-injection is finished.

Example
// Grab a handle to IconicJS and make some settings
var iconic = IconicJS({
  autoInjectSelector: 'img.iconic',
  pngFallback: 'assets/png',
  each: function (svg) {
    console.log('Injected an SVG! ' + svg.id);
  },
  autoInjectDone: function (count) {
    console.log('Auto injection of ' + count + ' SVGs complete. We did it.');
  }
});

Per-element PNG fallback

Since you might be using a single SVG styled in multiple ways, you can also define per-element fallbacks by adding a data-fallback or data-png attribute to your img tags to define a unique PNG for each context.

See examples/fallbacks for more details.

<style>
  .thumb-green {fill: #A6A93C;}
</style>
<img class="iconic thumb-green" data-src="svg/thumb-up.svg" data-fallback="png/thumb-up-green.png">

Methods

Inject

inject ([selector|element|array of elements], options, callback)

After your page loads you might also want to inject some SVGs. This is a common case when building single-page applications and using front-end libraries and frameworks like Angular, Backbone and Ember, or when making calls like jQuery.load(), that make DOM changes and add icons after the initial automatic injection occurs.

When you add new img tags, you can call inject() to pick those up and trigger the injection.

If you are dynamically adding an icon you've already served on your page or app, the iconic.js cache will already have it and save you a network call and parsing cost too.

  • You can pass inject a selector string, a single icon DOM element or array of DOM elements.

  • options - object
    {
      each: [function]
    }
    
    • each - function

    A function to call after each SVG is injected. Receives the newly injected SVG DOM element as a parameter.

  • callback - function

    A function to call once all the requested SVG elements have been injected. Receives a count of the total SVGs injected as a parameter.

Example
var iconic = IconicJS();
iconic.inject('img.my-selector', {
  each: function (svg) {
    // For each SVG injected
  }
}, function (count) {
  // Injection complete
});

Update

update ([selector|element|array of elements|null])

Calling update does a couple things:

  • Re-runs any Smart Icon update methods. Useful when you are making data-attribute or other changes to them.
  • If the icon has the iconic-fluid class, recalculate the current icon display size and show the approriately-sized responsive icon.

You can pass update a selector string, a single icon DOM element, array of DOM elements or nothing. Passing nothing will run update on all Iconic icons by using the svg.iconic class selector.

Example
var iconic = IconicJS();

// Update all icons matching a selector
iconic.update('.my-icons');

// Update one icon
var myIcon = document.getElementById('my-icon');
iconic.update(myIcon);

// Update several icons
var myIcons = document.querySelectorAll('.my-icons');
iconic.update(myIcons);

// Fire EVERYTHING!!!
iconic.update();