Ionicons Complete Guide: Modern Web, React, Vue & Mobile (2026)

1. Introduction: The Power of Cross-Platform Native Iconography

Building applications that simultaneously target mobile devices (via Capacitor, React Native, or PWAs) and responsive desktop browsers requires an icon system that respects conflicting operating system design conventions. While iOS interfaces emphasize smooth continuous fillets, subtle 1.5px/2px stroke outlines, and gentle tap feedback, Android Material Design favors bold, geometric silhouette fills and crisp sharp vertices.

Ionicons solves this fundamental design dichotomy by crafting every single concept into three synchronized, independent vector glyphs:

1. Outline (-outline): Delicate 32px stroke-based outlines featuring circular corner joints, perfectly harmonizing with Apple HIG (Human Interface Guidelines).
2. Filled (default): High-density solid silhouettes, ideal for active bottom-tab selections, pressed states, and primary callouts.
3. Sharp (-sharp): Squared-off vector joints and unfilleted geometric boundaries tailored to Google's Material Design principles.

On IconStash, you can browse all 1,300+ vector paths in the Ionicons Library, copy clean SVG code directly, or export optimized React JSX components.

2. The Three Architectural Styles: Outline, Filled, and Sharp

Understanding the geometric differences between Ionicons styles is essential for creating cohesive design systems:

3. Interactive Tri-Style Icon Switcher & Code Generator

Toggle between the three Ionicons variants below to inspect their underlying vector geometry in real time. Notice how the stroke joints and fills adapt, and view the live-generated React, Angular, and HTML code snippets:

4. Vanilla HTML & Web Components: The <ion-icon> Custom Element

Ionicons was engineered from day one around the W3C Web Components standard. The custom element <ion-icon> uses Shadow DOM to fetch and render raw SVGs asynchronously on demand. This provides automatic lazy loading, ensuring that only the SVGs actually visible in the DOM are downloaded over the network.

<!-- Include Ionicons Web Component Runtime via CDN -->
<script type="module" src="https://unpkg.com/[email protected]/dist/ionicons/ionicons.esm.js"></script>
<script nomodule src="https://unpkg.com/[email protected]/dist/ionicons/ionicons.js"></script>

<!-- Render icons by string name -->
<ion-icon name="heart-outline" style="font-size: 24px; color: #C1DD2D;"></ion-icon>
<ion-icon name="settings-sharp" size="large"></ion-icon>

<!-- Platform-Adaptive Mode: iOS renders outline, Android renders sharp -->
<ion-icon ios="heart-outline" md="heart-sharp"></ion-icon>

The size attribute accepts "small" (16px) or "large" (32px), while standard sizing is driven directly through CSS font-size and color via color (which inherits currentColor).

5. React & Next.js 15 Integration: Subpath Tree-Shaking

In React and Next.js applications, passing raw string names to web components can cause hydration mismatches in Server-Side Rendering (SSR). Instead, use the official React wrapper @ionic/react with direct subpath imports from ionicons/icons:

// 1. Install dependencies
// npm install @ionic/react ionicons

import React from 'react';
import { IonIcon } from '@ionic/react';
// Direct subpath import guarantees 100% tree-shaking
import { 
  homeOutline, 
  home, 
  analyticsOutline, 
  settingsOutline 
} from 'ionicons/icons';

interface SidebarItemProps {
  label: string;
  icon: string;
  activeIcon: string;
  isActive: boolean;
}

export function SidebarItem({ label, icon, activeIcon, isActive }: SidebarItemProps) {
  return (
    <a className={`flex items-center gap-3 px-4 py-2.5 rounded-lg text-sm font-medium transition-colors ${
      isActive ? 'bg-zinc-800 text-lime-400' : 'text-zinc-400 hover:text-white'
    }`}>
      <IonIcon 
        icon={isActive ? activeIcon : icon} 
        style={{ fontSize: '20px' }} 
        aria-hidden="true" 
      />
      <span>{label}</span>
    </a>
  );
}

6. Angular Modern Architecture: Standalone Components & addIcons()

Modern Angular (v17+) uses Standalone Components and strict signal-based reactivity. Ionicons provides the optimized addIcons() registry pattern to prevent bloat in enterprise Angular production bundles:

// app-header.component.ts
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { IonHeader, IonToolbar, IonTitle, IonButtons, IonButton, IonIcon } from '@ionic/angular/standalone';
import { addIcons } from 'ionicons';
import { heartOutline, settingsSharp, personOutline } from 'ionicons/icons';

@Component({
  selector: 'app-header',
  standalone: true,
  imports: [CommonModule, IonHeader, IonToolbar, IonTitle, IonButtons, IonButton, IonIcon],
  template: `
    <ion-header>
      <ion-toolbar>
        <ion-title>Enterprise Dashboard</ion-title>
        <ion-buttons slot="end">
          <ion-button aria-label="Favorites">
            <ion-icon name="heart-outline"></ion-icon>
          </ion-button>
          <ion-button aria-label="Settings">
            <ion-icon name="settings-sharp"></ion-icon>
          </ion-button>
        </ion-buttons>
      </ion-toolbar>
    </ion-header>
  `
})
export class AppHeaderComponent {
  constructor() {
    // Explicit registration guarantees exact Rollup tree-shaking
    addIcons({
      'heart-outline': heartOutline,
      'settings-sharp': settingsSharp,
      'person-outline': personOutline
    });
  }
}

7. Vue 3 Integration: Composition API & Vite Optimization

For Vue 3 and Nuxt 3 applications, Ionicons integrates seamlessly with the Composition API:

<!-- components/NavBar.vue -->
<template>
  <nav class="nav-container">
    <button @click="toggleActive" class="icon-btn" aria-label="Bookmark">
      <ion-icon :icon="isActive ? bookmark : bookmarkOutline" class="nav-icon"></ion-icon>
    </button>
  </nav>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { IonIcon } from '@ionic/vue';
import { bookmarkOutline, bookmark } from 'ionicons/icons';

const isActive = ref(false);
const toggleActive = () => {
  isActive.value = !isActive.value;
};
</script>

<style scoped>
.nav-icon {
  font-size: 24px;
  color: #C1DD2D;
  transition: transform 150ms ease;
}
.nav-icon:hover {
  transform: scale(1.1);
}
</style>

8. Mobile Cross-Platform Workflows: Capacitor, iOS & Android Adaptation

When developing mobile apps using Capacitor or React Native, displaying platform-authentic iconography significantly improves user satisfaction and App Store review ratings. Apple users expect thin, rounded outlines, while Android users expect geometric Material fills.

Ionicons provides automated platform detection out of the box. By setting both the ios and md attributes on any <ion-icon>, the component inspects navigator.userAgent (or the Capacitor device platform bridge) and dynamically selects the correct visual treatment:

<!-- Automatically serves heart-outline on iOS and heart-sharp on Android -->
<ion-icon ios="heart-outline" md="heart-sharp"></ion-icon>

<!-- Automatically serves share-outline on iOS and share-social-sharp on Android -->
<ion-icon ios="share-outline" md="share-social-sharp"></ion-icon>

9. Comprehensive Library Benchmark Comparison

Here is how Ionicons measures up against other top-tier icon systems in 2026:

Frequently Asked Questions