heroicons

Heroicons is a free, open-source icon set built by the Tailwind CSS team. It ships as plain SVG source you can copy straight into HTML, plus first-party framework packages (@heroicons/react, @heroicons/vue) so each icon can be dropped in as a component instead of hand-copied markup.

The library covers four icon families - 24x24 outline, 24x24 solid, 20x20 solid (“mini”), and 16x16 solid (“micro”) - so the same glyph set scales cleanly across page headers, inline text, and dense UI like table rows or badges. Every icon inherits color from CSS via currentColor, making them trivial to theme alongside Tailwind’s utility classes or any other styling approach.

The project intentionally keeps its scope narrow: the maintainers only accept bug-fix contributions, not new icons or new framework targets, which keeps the set consistent and the release cadence predictable rather than sprawling into a community-graveyard of half-supported variants.

What You Get

• Four ready-made icon families - 24x24 outline, 24x24 solid, 20x20 solid, and 16x16 solid - covering headers down to dense inline UI
• First-party @heroicons/react and @heroicons/vue packages with per-icon named exports (e.g. BeakerIcon) instead of a single monolithic import
• Plain SVG source for any icon, copy-pasteable directly into HTML with no build step or package install required
• Icons that inherit color via currentColor, so they restyle automatically with Tailwind utility classes or any CSS color rule
• A consistent naming and export convention (upper camel case, always suffixed Icon) across every size and framework package
• Deprecated-icon handling baked into the build so renamed/retired icons keep working with a @deprecated warning instead of breaking silently

Common Use Cases

• Dropping icons into a Tailwind CSS project’s buttons, nav bars, and form fields with matching visual language
• Building a React or Vue admin dashboard that needs a consistent, tree-shakeable icon set instead of a full icon-font
• Using the 16px/20px “micro”/“mini” solid styles for dense UI like table actions, badges, and inline status indicators
• Copying raw SVG markup into a static site or email template where installing an npm package isn’t practical

Under The Hood

Architecture

Heroicons isn’t a runtime library with application logic - it’s a source-to-package build pipeline. Hand-drawn SVGs live under src/{16,20,24}/{solid,outline}/, and scripts/build.js walks that source tree, optimizes each file with SVGO, and emits three parallel outputs: optimized raw SVGs (optimized/, mirrored into the root 16/, 20/, 24/ folders published as the bare heroicons npm package), React components (react/, transformed via @svgr/core and Babel into named exports like BeakerIcon), and Vue single-file components (vue/, compiled via @vue/compiler-dom). Each framework target ships as its own scoped package (@heroicons/react, @heroicons/vue) with its own package.json and exports map, so what breaks if the core abstraction changes is the shared naming convention enforced by scripts/verify-names.js, not any shared runtime code.

Tech Stack

The toolchain is pure Node.js build tooling with no runtime dependencies in the published packages themselves: SVGO 3 for SVG optimization/minification (with per-size svgo.*.mjs configs), @svgr/core plus @babel/core and @babel/plugin-transform-react-jsx to turn SVG into React components, @vue/compiler-dom to compile the same SVGs into Vue render functions, camelcase for deriving component names from filenames, and prettier/rimraf for output formatting and cleanup between builds. CI (.github/workflows/CI.yml) runs on GitHub Actions against Node 18, installing dependencies and running npm run build as its only check - there’s no separate lint or test job.

Code Quality

There is no conventional unit test suite; correctness is instead enforced structurally by scripts/verify-names.js, which diffs icon filenames across all four style directories (micro, mini, solid, outline) and fails the build if any style is missing an icon the others have, with an explicit allowance for icons deprecated out of the micro set. Generated framework code is auto-formatted (Prettier config in prettier.config.js) rather than hand-styled, and the packages ship hand-maintained .d.ts type declarations per icon/size via the exports map in each framework’s package.json. Contribution scope is deliberately narrow - the maintainers state they only accept bug-fix PRs, not new icons or new framework targets - which keeps the codebase small and consistent rather than sprawling.

What Makes It Unique

Heroicons’ distinguishing choice isn’t a novel rendering technique - SVG-to-component generation is a well-trodden pattern - but its four-tier size/style system (16px and 20px solid “micro”/“mini” variants alongside the standard 24px outline/solid pair) purpose-built for dense UI contexts like table rows and inline badges, plus being maintained by the Tailwind CSS team itself, which keeps its currentColor theming and naming conventions tightly aligned with how Tailwind projects already style things.