New Iconify documentation 21 Feb 2023

Iconify documentation has been restructured and many parts have been rewritten.

New documentation focuses on developer experience, trying to help developers find correct tools from Iconify ecosystem.

See new improved Iconify documentation.

Custom CSS in Iconify Icon web component 28 Jan 2023

Iconify Icon web component has been updated.

New version includes function to append custom CSS to icons: appendCustomStyle().

Function can be imported from:

• iconify-icon package.
• As static method from web component constructor.
• As method from any <iconify-icon> element instance.

There are several limitations:

• It affects all instances of <iconify-icon> rendered after function is called.
• It does not affect instances created before function call.
• You cannot add CSS only for one icon yet.

These limitations will be removed in future versions.

Example

This will change stroke-width from 2 to 1.5 in all icons, rendered after that function call.

SVG without width and height with Iconify components 27 Jan 2023

Iconify icon components have been updated.

New version includes ability to remove width and height properties from generated <svg>. Sometimes this is needed if you are using CSS to resize icon.

To remove width or height, set it to one of these values: "unset", "undefined", "none".

Example

Example usage in @iconify/vue component:

This will remove both width and height from rendered <svg> element.

Removing one attribute only

If you want to remove only one attribute, for example, width, you need to set value for height:

This will remove only width attribute.

Web component

This function is not available in iconify-icon web component because it won't work as expected.

Iconify for Tailwind CSS 11 Jan 2023

Iconify plugin for Tailwind CSS is available.

Plugin is in early development stage, but already fully functional.

It creates CSS for icons, using icons as background and mask images. This allows you to use icons without any components, without inlining SVG.

See Iconify for Tailwind package for details.

HTML

Example usage in HTML:

Generate CSS for icons with Iconify API 9 Jan 2023

Iconify API now can dynamically generate CSS for icons.

All you have to do is link to /{prefix}.css?icons=icon-names on API, where "{prefix}" is icon set prefix and "icon-names" is comma separated list of icon names.

This allows you to use icons without any components, without inlining SVG.

Monotone icons

Best part is, it works with monotone icons!

Monotone icons are rendered with color set to currentColor, just like icon fonts or inline SVG! How is it done? By using icon as mask image with background color set to currentColor.

See Iconify API documentation for examples.

Example

This example shows icons with hardcoded palette from Noto Emoji icon set.

Stylesheet link: https://api.iconify.design/noto.css?icons=1st-place-medal,2nd-place-medal.

It generates this stylesheet:

that you can use in HTML like this:

API query can be customised. See Iconify API documentation for more examples and parameters.

Monotone example

Stylesheet link: https://api.iconify.design/mdi-light.css?icons=account,account-alert,home.

It generates this stylesheet:

that you can use in HTML like this:

Parameters

API query can be customised.

You can change selectors, set hardcoded color for monotone icons, download generated stylesheet.

See Iconify API documentation for more examples and parameters.

Generate CSS for icons with Iconify Utils 2 Jan 2023

New functions for generating stylesheet for icons are available in Iconify Utils:

• getIconCSS() to generate CSS for one icon.
• getIconsCSS() to generate CSS for multiple icons.

What do these functions generate? A stylesheet, which renders icons as background or mask images.

To use icon in your project, all you have to do is generate stylesheet, then add basic element, such as <span> to render icon:

Examples

Example of stylesheet generated for one icon with hardcoded palette using getIconCSS():

Example of stylesheet generated for multiple monotone icons from Tabler Icons using getIconsCSS():

Background or mask

Generated code uses background or mask image for icons. What is the difference?

• Background image is used for icons with hardcoded palette.
• Mask image in combination with background color set to currentColor is used for icons without palette. This combination renders icon with current text color, making it easy to change icon color by changing text color.

Advantages

Advantages of using stylesheet for icons instead of inline SVG:

• Can be used with any framework. No need for special components.
• No extra elements in DOM.
• Instant rendering of animated icons.

However, there are also disadvantages:

• Cannot target specific element in icon, which makes things like changing stroke-width impossible. It has to be done at build time when providing icon data to getIconCSS() or getIconCSS().
• Cannot mix currentColor and hardcoded palette in icon. This is not an issue when using Iconify icon sets, as such icons are not allowed, but it can be an issue when using custom icons.

Documentation

See documentation for more details:

• getIconCSS() documentation.
• getIconsCSS() documentation.

All icon components updated 29 Nov 2022

All icon components have been updated!

This release fixes a bug in icon loading function, which could cause Promise instance to hang if user tries to load icon that does not exist.

New Iconify API software with icon search engine 16 Nov 2022

Iconify API has been rewritten using modern development process and is now running on Iconify public API servers.

This is a huge release that has been in development for a long time.

API features

New version is fully open source, written in TypeScript. It can:

• Serve icon data to icon components and dynamically generate SVG.
• Provide list of icon sets and list of icons.
• Search icons.
• Import icon sets from various sources and automatically keep them up to date without restarting server (no documentation yet, but code is there).

It is a Node.js HTTP server, does not require installing any additional software. All you need to do is install NPM dependencies, build it, optionally configure it and start server.

API documentation

See Iconify API software documentation.

New documentation includes documentation for API queries, including search engine documentation. Developers can use it to create various projects that allow users search and select icons, for example, icon pickers for website builders or theme customiers.

Host your own Iconify API with open source icon sets or your own icons! Build applications for searching, browsing and selecting icons, integrate them in various tools! Everything you need is finally available.

If you have any questions, please join discord server or ask them at API source repository.

Icon web component updated 8 Oct 2022

IconifyIcon web component has been updated!

This version fixes few bugs and opens up shadow root for external access, allowing developers to mess with icon content.

New major versions of icon components, utils, tools 8 Sep 2022

After several months of hard work, new major versions of many packages have been released:

• Iconify Icon web component version 1.0.0.
• SVG framework version 3.0.0.
• New major versions of all icon components.
• Iconify Utils version 2.0.0.
• Iconify Types version 2.0.0.

Additionally, new minor version of Iconify Tools has been published, which uses updated utils and types packages.

What's new:

• In types, new properties for icon set were added: lastModified that shows last modification time, tags for icon set information that can be used to filter icon sets by tags instead of categories.
• Web component is finally stable. It is intended to replace old SVG framework and framework specific components. Unlike older icon components, web component works extremely well with server side rendering.
• Alignment properties have been removed from all icon components. Alignment seemed like a good idea a while ago, but in reality it is not used and just bloats package for no reason. If you do use alignment, web component supports preserveAspectRatio property that is passed to <svg>.
• Render modes for icon components, though not all components support it.
• Many internal changes everywhere, designed to improve performance and reduce bundle size.

Next major version of icon components 30 June 2022

Big update for icon components!

New web component has been published as beta version. New major versions of old icon components have been published, using @next tag.

What's new?

• Web component.
• New icon rendering modes.
• Many internal changes, resulting in faster components and smaller bundle size.

Web component

Unlike other icon components, web component renders icon in shadow DOM. This means:

• Icon is separate from main document, resulting in better performance and shallower DOM tree.
• It works great with server side rendering! All UI frameworks see is <iconify-icon /> tag, actual icon is rendered only in browser independent of UI framework used.

Web component can be used without any UI framework, performing better than SVG framework.

It can also be used with most UI frameworks:

• Svelte, Vue 2, Vue 3, Ember, Lit (and SSR frameworks that use those frameworks) work with web component as is, do not require any custom wrappers.
• React can work as is, but with few caveats, such as class instead of className. There is a wrapper for React that allows using className and provides typings: @iconify-icon/react.
• SolidJS currently has issues working with web components and requires custom wrapper. See @iconify-icon/solid.

Rendering modes

Web component and almost all old icon components now support rendering modes. Icon can be rendered as SVG, as SPAN with background or as SPAN with mask.

This is mostly done to fix browser issues with SVG animations. If icon is rendered as SVG, animations do not start until an entire document is loaded, which can be broken by small things like ad or tracker failing to load. If icon is rendered as background or mask, animations work as expected.

See rendering modes documentation.

Alignment

Older versions of icon components had alignment attributes. They could be used to control alignment of icon content, when both width and height of icon were set and did not match width/height ratio of icon content. It was basically a wrapper for SVG preserveAspectRatio attribute.

In new version of icon components alignment attributes are no longer supported. They weren't widely used, but they did increase bundle size by significant amount.

If you do need to use alignment attribute, web component supports preserveAspectRatio attribute, which works exactly as in SVG. So switch to web component and adjust your code.

Update for Sketch plug-in 15 June 2022

New version of Iconify plug-in for Sketch has been published.

This update cleans up animations in icons before importing, allowing icons that use SVG animations to be imported to Sketch.

Download is available on GitHub repository for plug-in.

Twitter and Discord 29 May 2022

Support for Iconify is now available on:

• Anthony Fu's discord server in #iconify channel.
• You can find me on Twitter.

Update

Twitter is no longer used. Updates are now posted on Mastodon.

Iconify Icon web component 1 May 2022

New <iconify-icon /> web component has been released.

See NPM package description for details.

This is a major milestone for Iconify project. It drastically improves developer experience by proving modern web component to render icons.

Example usage:

It is as easy to use as SVG framework, but without extra hassle of watching DOM for placeholders. It also works with any component framework.

Why is it better than existing SVG framework and icon components?

Shadow DOM

Unlike SVG framework and older components, <iconify-icon /> renders icon in shadow DOM. What does it mean? It means icon is separate from parent HTML document.

Advantages of using shadow DOM:

• No conflicts with document's stylesheet.
• Works perfectly with SSR.

Server side rendering is becoming more common, hydration process can be messy, especially when icons supposed to contain unique ids. This has been a big headache for icon components for a while. With web component, server script simply renders <iconify-icon />, without actual icon code and during hydration frameworks such as React do not check icon content. Which means several things: rendering actual icon on server side is no longer required, no need to generate unique ids for things like masks, web component can load icon data from API without caring about what framework thinks of it because as far as frameworks are concerned, they only render one simple tag.

Render modes

SVG 2 animations have not been popular and for a good reason: currently in browsers animations do not start until entire document is loaded. Small things like slow loading ad can prevent animation from working.

How to solve it? It can be solved by rendering icon as background image or as mask image. Background and mask images are not affected by document's timers.

<iconify-icon /> supports several render modes to solve this issue. Icon can be rendered as <svg /> or as <span /> with inline style (article about it will be added soon to documentation).

<span /> is used to render icons with SVG 2 animations. In addition to solving animation delay issue, SVG 2 animations perform much better when used as background or mask.

However, without animations icons perform better as <svg />, so both modes are supported and can be toggled using mode attribute.

Mode can be toggled by using mode attribute.

SVG Framework and icon components updated 31 Mar 2022

SVG framework and icon components have been updated!

This release includes the following changes:

• Replaced code that used optional chaining introduced in previous update. Unfortunately some developers still use outdated build tools that cannot parse modern JavaScript, mostly Vue 2 developers.
• Replaced unnecessary complex function that validated icon sets with a simpler function. This change resulted in smaller bundle size for all icon components. Difference is about 5% - 8%, depending on component.

SVG Framework and icon components updated 19 Mar 2022

SVG framework and icon components have been updated!

This release is mostly internal changes, which do not affect functionality:

• Support for very old browsers, such as Internet Explorer has been dropped.
• Many packages have switched to Vitest for unit testing and Unbuild for building code.
• Fixed bug that caused loadIcon() to not reject Promise instance when icon was not found.

Vue and React components updated 28 Feb 2022

This update addresses the following issues:

• Fixes SSR rendering in Vue 3 component.
• Fixes imports for offline icon components.

Major icon sets restructuring 14 Feb 2022

Iconify icon sets repository received biggest update.

Icon sets are updated automatically every few days by an automated script. Until now, the script was using old code that didn't do proper validation. With the release of Iconify Tools 2, it is now possible to properly analyse and validate icons.

Update script has been rewritten, all icon sets have been re-checked, which resulted in major update of icon sets repository. Every single icon set file was affected.

Additionally, there are few other changes:

Unmaintained icon sets

Icon sets that are no longer maintained by their authors have been moved to new "Archive / Unmaintained" category.

Removed icon sets

15 icon sets were removed.

When Iconify project development started several years ago, there were very few good icon sets. Many icon sets were designed as fonts. Icons in those icon sets were usually very badly designed, alignment was way off and today they are no longer maintained.

Removed icon sets will not appear on Iconify website and will not show up in search results.

However, icon data is still available on both NPM and API, so anyone using those icons can continue using them without interruption. Icon sets and icons are never removed from Iconify, they are just marked as hidden but continue to be usable.

New icon sets

Several new icon sets were added.

Newly added icon sets include FontAwesome version 6, several icon sets with flags.

Because FontAwesome version 6 redesigned most of the icons, it was added separately from FontAwesome version 5, so both versions are available.

Around.co sponsorship 12 Feb 2022

Huge thanks to Around for sponsoring Iconify plugin for Figma!

Around is an excellent collaboration tool designed for developers. Check them out!

Working on Iconify is a full time job and servers cost money, while open source development does not pay, so sponsorships are very welcome. Thanks to Around for reaching out and offering to help out.

You can contribute too! If you are using Iconify in your projects, please consider supporting Iconify.

SVG Framework and icon components updated 24 Jan 2022

SVG framework and icon components have been updated!

This version introduces new function: loadIcon(). It is a simple to use function that uses Promise class to load icon data asynchronously.

See SVG framework documentation or icon component documentation for details.

New website 20 Jan 2022

Welcome to the new iconify.design website!

Website has been rebuilt from the ground up. Some parts still require minor updates, but overall it is a massive improvement over the old website.

If you notice any bugs, please open a ticket at Iconify documentation repository.

ES modules support 11 Nov 2021

New minor versions of all icon components, including SVG Framework, have been published.

All packages were updated to export ES modules, build process has been changed to rely on ES modules. No more CommonJS! Bundling ES modules resulted in smaller bundle size for all icon components.

Loading icons from API has been re-written as well. New code is smaller and have full test coverage.

New icon components are now stable 9 Aug 2021

Stable versions of new icon components have been published.

All components can load icons on demand from Iconify API and support custom API providers, matching functionality of SVG Framework.

New versions of components:

• Iconify for React: 3.0.0 (Use @iconify/react to install it)
• Iconify for Vue 3: 3.0.0 (Use @iconify/vue to install it)
• Iconify for Vue 2: 1.0.0 (Use @iconify/vue2 to install it)
• Iconify for Svelte: 2.0.0 (Use @iconify/svelte to install it)

Iconify for React with API package (@iconify/react-with-api) has been deprecated.

Source code for new icon components is available on GitHub.

Iconify icon components documentation.

New website for icon sets 7 Aug 2021

Icon sets section of website has been completely rewritten.

New version is based on Svelte version of upcoming Iconify Icon Finder, with addition of server side rendering.

The same code base is shared with new Iconify for Figma plug-in and Iconify for Sketch plug-in and can be used to create custom icon finder.

Ember component is available 20 July 2021

Ember component is available!

Click here to see Ember component documentation.

SVG Framework and icon components updated 1 July 2021

SVG Framework version 2.0.3 is available!

This version fixes support for SVG animations. All components have been updated as well.

SVG Framework version 2.0.2 16 June 2021

SVG Framework version 2.0.2 is available!

This version fixes compatibility issue with Turbolinks and similar website accelerators.

SVG Framework version 2.0.0 7 May 2021

SVG Framework version 2.0.0 is available!

After months of hard work, new version of SVG Framework is stable and is ready to be used in production.

To learn more about new version of SVG framework and components, visit SVG framework 2.0 documentation and for Iconify components documentation.

All icon components support API 7 May 2021

All icon components have been rewritten.

From now on, all icon components can load icons on demand from Iconify API and support custom API providers, matching functionality of SVG Framework.

New versions of components:

• Iconify for React: 3.0.0 alpha 0 (Use @iconify/[email protected] to install it)
• Iconify for Vue 3: 3.0.0 alpha 0 (Use @iconify/[email protected] to install it)
• Iconify for Vue 2: 1.0.0 alpha 0 (Use @iconify/vue2 to install it)
• Iconify for Svelte: 2.0.0 alpha 0 (Use @iconify/[email protected] to install it)

Iconify for React with API package (@iconify/react-with-api) has been deprecated.

Source code for new icon components is available on GitHub.

Documentation has been rewritten for new components Iconify icon components documentation.

SVG Framework version 2.0.0 Release Candidate 1 26 Aug 2020

Multiple packages based on Iconify 2 framework have been updated:

• Iconify SVG framework: 2.0.0 release candidate 1
• Iconify for React with API: 1.0.0 release candidate 1
• New component: Iconify for Vue 3

Also Iconify documentation has been rewritten and most important parts of it are complete.

To learn more about new version of SVG framework and components, visit SVG framework 2.0 documentation and for Iconify components documentation.

New documentation is available 24 July 2020

New documentation is available! Click here to visit new documentation.

Old documentation was badly outdated and almost useless. New documentation has built to be easy to edit and update.

While old documentation was focused on SVG framework, new documentation covers all topics. New topics can be easily added. All documents are written in Markdown with a bit of custom syntax. It covers topics about various components, Iconify API, documentation for developers, tutorials on converting icons and many other topics.

Many parts of documentation are under construction. However, it already contains much more information than old documentation did. Documentation is updated almost daily.

New documentation is available on Iconify GitHub repository. Instructions for building documentation are avaialble in README.md file. Anyone can contribute.

Iconify 2 updates 2 July 2020

Multiple packages based on Iconify 2 framework have been updated:

• Iconify SVG framework: 2.0.0 beta 2
• Iconify for Vue: 1.0.2
• Iconify for Svelte: 1.0.0 beta 4
• Iconify for React: 2.0.0 beta 2
• Iconify for React with API: 1.0.0 beta 2

Click here to access new code.

Documentation on this website is in process of being rebuilt. For now it is for Iconify 1.0. Iconify 2.0 is not fully backwards compatible, so you should look at GitHub for documentation. If you have any questions, open an issue on Iconify GitHub repository.

Iconify for React with API

Iconify for React with API is a new package. It is similar to Iconify for React, but with added support for Iconify API.

When using Iconify for React, you must bundle used icons and pass icon data to component. New component, in addition to data syntax, supports referencing icon by name. Component will automatically retrieve icon data from Iconify API and will render it. Component caches retrieved data in local storage, so it won't need to retrieve icon data again after page reloads.

Example of a checkbox component using Iconify for React with API:

Version 1.0.7 has been released 24 June 2020

Iconify version 1.0.7 has been released.

This version includes new bundle for SVG framework that does not include Iconify API support.

To use Iconify SVG framework without Iconify API support, instead of including "iconify.min.js", include "iconify.without-api.min.js"

Iconify SVG framework without Iconify API support works only work with icons that are bundled. That means you can use it offline, provided that you have added all icons you need in bundle.

Click here for icon bundles documentation.

Iconify 2.0, which is currently in development, will include similar bundle without API support.

Iconify 2.0 beta, Iconify for Vue, Iconify for Svelte 30 Apr 2020

Iconify 2.0 beta, Iconify for Vue, Iconify for Svelte.

After several months of hard work, Iconify 2.0 has reached beta stage! It is also used as base for brand new Vue and Svelte components as well as rewritten React component.

Iconify 1.0 was a designed as a proof of concept. It was built to prove that there can be a decent replacement for icon fonts. However, even though it worked very well, it was not built up to modern standards. Iconify 2.0 was rebuilt from ground up, using modern technologies.

What's new in Iconify SVG Framework 2.0?

• API redundancy. Internet is not stable, downtime happens, which is biggest issues with services that rely on third party servers. Iconify 2.0 has built in redundancy, so if API server is unreachable, Iconify attempts to retrieve icons from one of backup API servers.
• New syntax! Major differences:
  • <iconify-icon> tag is gone.
  • Only tags <span> and <i> are supported.
  • class="iconify" now defaults to block icon (without vertical-align).
  • class="iconify-icon" defaults to inline icon (former class="iconify").
  • Iconify SVG Framework watches for attribute changes, except for data-inline attribute. That means if you, for example, change data-icon attribute on a rendered icon, SVG framework will detect change and update icon.

You can still use data-inline attribute to change behavior. Same code for Iconify 1.0 and 2.0:

What's new for developers?

• TypeScript support. Iconify was rewritten in TypeScript and exports all types, making it easy to use it with TypeScript.
• Reusable shared code. Iconify 2.0 uses modular approach to code, allowing developers to pick what functionality they want, making it easy to build custom implementations. Vue, Svelte and new React components are proof that it works.
• SVG framework and components are now in one big monorepo, making it easy to develop and test common code.
• Simple build process using modern development tools. Build process uses TypeScript and Rollup, making it easy to create custom bundles.
• Click here to access new code.

Documentation on this website is in process of being rebuilt. For now it is for Iconify 1.0. Iconify 2.0 is not fully backwards compatible, so you should look at GitHub for documentation. If you have any questions, open an issue on Iconify GitHub repository.

Version 1.0.6 has been released 21 Apr 2020

Iconify version 1.0.6 has been released.

This version fixes bug that prevented inline style from being passed from placeholder to SVG.

Version 1.0.5 has been released 31 Mar 2020

Iconify version 1.0.5 has been released.

This version fixes issues when using Content Security Policy headers.

If you are using CSP with Iconify 1.*, you need to add the following URLs to script-src: https://code.iconify.design/ and https://api.iconify.design/.

For upcoming version 2 of Iconify SVG framework, header will require addition of 2 more URLs: https://api.simplesvg.com and https://api.unisvg.com. Internet is not stable, errors do happen (downtime, routing errors). Iconify version 2 has built in redundancy to mitigate internet failures. If default API cannot be reached within a second, it will attempt to load icons from backup API. Therefore backup API needs to be added to list of allowed script sources.

Version 1.0.4 has been released 1 Feb 2020

Iconify version 1.0.4 has been released.

This version allows importing @iconify/iconify into TypeScript projects.

Iconify plug-in for Figma is available 1 Aug 2019

Iconify plug-in for Figma is available. See GitHub repository.

With Iconify plug-in for Figma designers can easily insert icons in their designs. Plug-in includes icon search, ability to browse collections, select any icon and insert it into current document.

Few screenshots of Figma plug-in UI:

Version 1.0.3 has been released 18 July 2019

Iconify version 1.0.3 has been released.

This version allows importing @iconify/iconify into projects then bundling it with WebPack.

It also adds new function getSVGObject() that can be used to develop Vue and Angular components.

Version 1.0.2 has been released 3 May 2019

Iconify version 1.0.2 has been released.

This version fixes IconifyConfig object that can be used to set custom Iconify configuration:

Version 1.0.1 has been released 14 Apr 2019

Iconify version 1.0.1 has been released.

This version includes 2 changes:

1. You can add Iconify to WebPack projects by including @iconify/iconify:

2. Support for title attribute:

Title will be rendered as tag inside SVG.

Version 1.0.0 has been released 24 Mar 2019

Iconify version 1.0.0 has been released.

Iconify has been in pre-release state for many months. All issues have been fixed and fixes have been thoroughly tested, so it is time to release a stable version.