How to Use Heroicons in Tailwind CSS, React & Next.js: The Complete 2026 Guide

1. The Heroicons Philosophy: Optical Sizing for Tailwind

Most icon collections draft glyphs on a single arbitrary grid (typically 24x24) and rely on CSS scaling (e.g., width: 16px; height: 16px) to shrink icons into buttons or table rows. In practice, downscaling an icon with fine lines causes fractional subpixel aliasing: strokes split across physical display pixels, creating muddy gray edges and diminished visual contrast.

Heroicons v2 solves this by treating optical weight as a first-class engineering concern. The library ships four distinct variations for each concept, each drawn from scratch on its target grid:

For more insights on setting up pixel-aligned icon grids in modern apps, read our technical deep dive on Pixel-Perfect SVG Grids and Scaling.

2. Package Setup & Subpath Imports

Tailwind Labs publishes official packages for React and Vue. Install the library with your package manager:

# React / Next.js / Remix
npm install @heroicons/react

# Vue 3 / Nuxt
npm install @heroicons/vue

The Subpath Import Rule

Unlike monolithic packages that bundle all variants together, @heroicons/react separates each optical style into its own clean subpath export. Always import directly from the relevant subpath:

// 24x24 Outline (1.5px stroke)
import { Bars3Icon, BellIcon, MagnifyingGlassIcon } from '@heroicons/react/24/outline';

// 24x24 Solid
import { HeartIcon as HeartSolidIcon, StarIcon } from '@heroicons/react/24/solid';

// 20x20 Mini (solid)
import { ChevronDownIcon, CheckIcon } from '@heroicons/react/20/solid';

// 16x16 Micro (solid)
import { XMarkIcon as XMarkMicroIcon, PlusIcon } from '@heroicons/react/16/solid';

3. Tailwind CSS v4 & v3 Integration Patterns

Heroicons components are designed to receive Tailwind utility classes seamlessly via their className prop. Outline icons use stroke="currentColor" fill="none", while Solid, Mini, and Micro icons use fill="currentColor".

Pattern A: Accessible Action Buttons with Mini Icons

When pairing icons with standard text buttons, the 20/solid (Mini) set provides the exact optical balance required for standard 36px/40px button heights:

import { ArrowDownTrayIcon, PlusIcon } from '@heroicons/react/20/solid';

export function ActionButtonGroup() {
  return (
    <div className="inline-flex items-center gap-3">
      <button className="inline-flex items-center gap-x-2 px-3.5 py-2 bg-neutral-900 hover:bg-neutral-800 text-neutral-200 hover:text-white border border-neutral-700/60 rounded-lg text-sm font-medium shadow-sm transition-all">
        <ArrowDownTrayIcon className="size-5 text-neutral-400" aria-hidden="true" />
        <span>Export Data</span>
      </button>

      <button className="inline-flex items-center gap-x-2 px-3.5 py-2 bg-lime-400 hover:bg-lime-300 text-neutral-950 rounded-lg text-sm font-bold shadow-sm transition-all">
        <PlusIcon className="size-5 text-neutral-950" aria-hidden="true" />
        <span>Create Project</span>
      </button>
    </div>
  );
}

Pattern B: High-Density Table Actions with Micro Icons

In dense data tables or status badges, 20px icons overwhelm small text. The 16/solid (Micro) variant integrates cleanly with 12px/13px typography:

import { CheckCircleIcon, ExclamationCircleIcon } from '@heroicons/react/16/solid';

export function DeploymentStatusBadge({ status }: { status: 'deployed' | 'failed' }) {
  if (status === 'deployed') {
    return (
      <span className="inline-flex items-center gap-x-1.5 px-2 py-0.5 rounded-md text-xs font-medium bg-emerald-950/60 text-emerald-300 border border-emerald-800/40">
        <CheckCircleIcon className="size-4 text-emerald-400" aria-hidden="true" />
        Active v2.4
      </span>
    );
  }

  return (
    <span className="inline-flex items-center gap-x-1.5 px-2 py-0.5 rounded-md text-xs font-medium bg-rose-950/60 text-rose-300 border border-rose-800/40">
      <ExclamationCircleIcon className="size-4 text-rose-400" aria-hidden="true" />
      Build Failed
    </span>
  );
}

4. Tree-Shaking Benchmarks & Next.js 15 Server Components

We measured the production build impact of Heroicons across multiple bundling strategies using Rollup and Vite 6:

Because Heroicons components do not use client hooks or React context, they render directly into static HTML strings on the server inside Next.js App Router. This means your visitors download zero JavaScript overhead for icons on initial page load.

5. Heroicons vs. Lucide vs. Tabler vs. Phosphor

How does Heroicons compare against the broader open-source iconography landscape? Here is the complete engineering matrix:

Explore our dedicated comparison hub to see side-by-side vector differences: Lucide vs Heroicons Comparison.

6. Browse & Export All 1,176 Heroicons on IconStash

Need Heroicons without installing an npm package? On IconStash, all 1,176 Heroicons (including 24px Outline, 24px Solid, and 20px Mini variants) are available with instant search and one-click export:

• JSX & TSX Export: Copy self-contained React components pre-configured with Tailwind classes and aria-hidden="true".
• Raw SVG Copy: Clean, optimized vector markup ready to paste into Vue templates, Svelte files, or static HTML.
• Cross-Set Concept Search: Search for any UI concept (like bell-icon or user-icon) and see how Heroicons renders against 27 other open-source icon libraries.

Frequently Asked Questions