Ionicons: a 1,300-icon set with a lazy-loading web component

What Ionicons is for, and who should pick it up

Ionicons is an open-source icon set of 1,300 icons, per the README, built by Ionic for Ionic Framework. Each app icon ships in filled, outline and sharp variants so the same interface can look native on both Material Design and iOS. That variant system is the reason the set exists in the form it does: the README says Ionicons "was built for Ionic Framework, so icons have both Material Design and iOS versions."

The audience is narrower than the icon count suggests. If you are already in an Ionic app, the package is bundled and you write no install step at all. If you are not, the README is explicit that the pack is "by no means limited to it" and can be used "wherever you see fit, personal or commercial." That second group is the one that has to make a decision, because outside Ionic you are choosing a component that fetches SVGs at runtime rather than a stylesheet you drop in once.

What it is not: a design system. There is no spacing scale, no illustration set, no animated icon library. It is a flat set of UI glyphs with three stylistic variants and a platform switch.

How the ion-icon web component loads an SVG

The mechanism is a Stencil-built web component, which the repository layout confirms through stencil.config.ts and the src/ directory. The README describes the runtime behaviour: "The component will dynamically load an SVG for each icon, so your app is only requesting the icons that you need." It goes further than a simple lazy fetch. Icons that are below the fold and hidden from view "do not make fetch requests for the svg resource."

That is the real design decision in this project. A traditional icon font downloads every glyph in one file whether or not the page uses them. Ionicons inverts it: one network request per visible icon, gated on visibility. For a page with six icons this is a clear win. For a dense toolbar with sixty icons, you have traded one cached font file for sixty requests, and the practical result depends on your HTTP setup rather than on the library.

The component resolves icon URLs against an asset path. The README documents setAssetPath for pointing that root somewhere else, which is how you self-host the SVGs instead of pulling them from a CDN. The package also exposes ./icons as an importable module, so the named-icon approach through addIcons is available when you would rather bundle than fetch.

Installing Ionicons and rendering a first icon

Inside Ionic Framework there is nothing to install. The README states Ionicons is "packaged by default, so no installation is necessary." For everything else, the documented path is a script tag placed near the end of the page, right before the closing body tag. The README gives this example, using esm.sh as the host:

<script type="module" src="https://esm.sh/ionicons@latest/loader"></script>
<script nomodule src="https://esm.sh/ionicons@latest/loader"></script>

After that script runs, the ion-icon element is defined and you populate the name attribute with a built-in icon name. The README's example is a heart:

<ion-icon name="heart"></ion-icon>

You should see the filled heart glyph. The variants follow a naming convention rather than a separate attribute: the filled variant is the bare name, outline appends -outline, and sharp appends -sharp. The README shows all three side by side, and notes that logo icons carry neither suffix.

<ion-icon name="heart"></ion-icon> <!--filled-->
<ion-icon name="heart-outline"></ion-icon> <!--outline-->
<ion-icon name="heart-sharp"></ion-icon> <!--sharp-->

Sizing is either the size attribute with the pre-defined values small and large, or a font-size CSS property on the element. The README recommends pixel sizes that are multiples of 8. Colour is set with the standard color CSS property. For outline icons you can tune the stroke with the --ionicon-stroke-width custom property, whose default the README gives as 32px.

ion-icon {
  font-size: 64px;
  color: blue;
  --ionicon-stroke-width: 16px;
}

If you would rather not fetch from a CDN, the README shows the self-hosted route through setAssetPath plus addIcons, importing the individual icons you need from 'ionicons/icons' and pointing the asset root at your own directory.

import { setAssetPath, addIcons } from 'ionicons';
import { add, logoIonic, save } from 'ionicons/icons';

setAssetPath(`${window.location.origin}/public/svg/`);
addIcons({ add, logoIonic, save });

With that in place, the README says a name like heart resolves to <root>/public/svg/heart.svg.

Custom SVGs, platform switching and the limits of each

Two features deserve scrutiny because they are where the documentation is thinnest.

The first is the src attribute for custom icons. The README says the URL "must be accessible from the webpage that's making a request for the image," and adds a hard constraint: the external file "can only be a valid svg and does not allow scripts or events within the svg element." That is a security boundary, not a stylistic preference, and it means an SVG carrying an inline script or an event handler will not behave the way its author intended.

The second is the md and ios attributes for platform-specific icons. You supply two different names and the component picks one based on platform. This is genuinely useful in an Ionic app that targets both stores. Outside Ionic, it is less obviously worth the indirection, since you probably already know which platform you are rendering for and can pass a single name.

The limitation that will bite hardest is the variant gap. The README states plainly that logo icons do not have outline or sharp variants. So a row of app icons using heart-outline and heart-sharp cannot be matched with logoIonic-outline, because that variant does not exist. Any interface that mixes brand marks with UI glyphs will show a stylistic mismatch, and there is no documented workaround short of supplying your own SVGs through src.

Where Ionicons is the wrong tool

The visibility-gated fetch is the feature to think hardest about. It assumes a browser environment where IntersectionObserver-style visibility tracking is meaningful. If you are rendering icons in an email template, a PDF pipeline, a canvas, or a server-side string that never becomes a live DOM, the lazy loader has nothing to observe and you get no icon. In those cases you want the raw SVG files, not the component.

It is also a poor fit when you need icons in a context the README does not cover. The documented integration surface is HTML through ion-icon, plus the setAssetPath and addIcons imports. There is no documented React component export, no Angular module, no Flutter package, and no React Native package. Those are common things people search for, and the README does not answer them. If your stack needs a first-party binding, verify that one exists before you plan around it.

Finally, the runtime fetch model gives you a dependency on network resolution at render time. A page that renders an icon name with no matching SVG will simply show nothing, and the README does not describe an error state or a fallback glyph.

Ionicons versus a general-purpose icon library

The closest comparison is with icon libraries that ship as a single font or a single sprite sheet plus per-framework wrappers. The difference is architectural, not aesthetic. A font-based library trades one upfront download for zero per-icon requests; Ionicons trades per-icon requests for the guarantee that off-screen icons cost nothing. Pick based on how many icons a typical view shows and how much of that view is below the fold.

The variant model is the other real difference. Ionicons bakes platform specificity into the icon set itself: filled, outline and sharp, plus md and ios attributes that select between two names at runtime. A general library usually gives you one visual style and expects you to pick a different library if you want another. Ionicons instead asks you to remember a naming convention, and the convention has a documented hole for logos.

If your requirement is a webfont you can subset and self-host with no JavaScript, Ionicons is not that, and the README does not present it as that.

Maintenance, licence and what an upgrade costs

The repository is not archived, and the last push was on 2026-07-28, which is recent enough that describing it as maintained is fair on the evidence available. Release v8.1.0 is dated 2026-07-28. The previous release, v8.0.13, is dated 2025-07-08, so roughly a year separates them. That cadence matters if you are pinning a version: the README's script example uses ionicons@latest, and you can substitute a pinned version instead, which the README demonstrates with 8.0.0.

Upgrade cost concentrates in the icon names. The README points to the 5.0 release notes as the place where icon deletions and renames were listed, which tells you that renames are a real category of change in this project's history. A rename in a later release would break an ion-icon name attribute silently, since the component renders nothing when it cannot resolve a name. Note also that package.json still declares version 8.0.13 while the newest release is tagged v8.1.0, a discrepancy worth checking before you trust the version field.

The licence is MIT, stated in the README and confirmed by the LICENSE file in the repository root. That permits commercial use. One caveat is stated in the README itself rather than by the licence: all brand icons are trademarks of their respective owners, and their inclusion does not indicate endorsement by Ionic or the reverse. That is a trademark question separate from the copyright licence, and it is the part to raise with whoever handles that for your organisation.

Editorial conclusion

Adopt Ionicons if you are building on Ionic Framework, where it ships by default, or if you want a single web component that fetches only the SVGs in view. Do not adopt it if you need a static webfont with no runtime fetch, or if you rely on logo marks in outline and sharp variants, because the README states logo icons have neither. Before committing, check that the names you use exist in the variant you want, and confirm that your CSP allows requests to the asset path the component resolves at runtime, since that path is what setAssetPath changes.

Frequently asked questions

Official sources

1. ionic-team/ionicons on GitHub
2. License: MIT
3. Project website
4. README
5. Releases