Heroicons: Tailwind's SVG icon set, as raw files or React and Vue components

What Heroicons solves, and who it is actually for

Icon fonts and ad-hoc SVG folders create two recurring problems: icons that cannot be recolored without a second asset, and a licensing question every time someone copies a file into a repository. Heroicons answers both by shipping plain SVG whose stroke or fill is set to `currentColor`, so the icon takes the surrounding text color, and by putting the whole set under MIT. The README describes the project as "Beautiful hand-crafted SVG icons, by the makers of Tailwind CSS", available as basic SVG and through first-party React and Vue libraries.

The audience is narrower than the icon count suggests. The primary path is a React or Vue codebase, where icons arrive as individually imported components rather than a sprite sheet. A second path suits anyone who just wants markup: copy the source from heroicons.com and inline it. There is no icon font, no sprite build step, and no runtime lookup, which means the icons you import are the icons in your bundle and nothing else.

The four variants and how the packages are structured

The set is not one grid. It is four, and the import path encodes which one you get. The 24x24 outline icons come from `@heroicons/react/24/outline` or `@heroicons/vue/24/outline`; the 24x24 solid icons from `/24/solid`; the 20x20 solid icons from `/20/solid`; and the 16x16 solid icons from `/16/solid`. Outline exists only at 24x24. If your design calls for a 16px outlined glyph, the set does not offer one, and you will be scaling the 24px outline down or switching to a solid variant.

Naming follows one rule: upper camel case with the word `Icon` appended. `BeakerIcon` is the example the README uses. That suffix is what makes the components distinguishable in a JSX or template file, and it is also the thing people get wrong when importing from memory.

The build is scripted rather than hand-curated. The `package.json` scripts run SVGO with a per-variant config file (`svgo.24.outline.mjs`, `svgo.20.solid.mjs`, `svgo.24.solid.mjs`, `svgo.16.solid.mjs`) over `src/`, writing optimized output into `optimized/` and then copying into `16/`, `20/` and `24/`. Separate `build-react` and `build-vue` scripts generate the framework packages from the same source. The practical consequence is that the raw SVG, the React components and the Vue components are generated from one set of source files, so they should not drift apart between releases.

Installing Heroicons and rendering a first icon in React

Install the React package from npm. The README gives this exact command:

npm install @heroicons/react

Import a single icon from the variant path you want and render it as a component. The README's example uses the solid 24x24 set and a Tailwind class for color:

import { BeakerIcon } from '@heroicons/react/24/solid'

function MyComponent() {
  return (
    <div>
      <BeakerIcon className="size-6 text-blue-500" />
      <p>...</p>
    </div>
  )
}

You should see the beaker glyph at 24px, tinted blue. The color comes from `text-blue-500` because the icon is configured to be stylable through the `color` CSS property; the README states that both icon styles are preconfigured this way. If you are not using Tailwind, an inline `style={{ color: '#3b82f6' }}` or any CSS rule targeting the element will do the same job.

For Vue the shape is the same with a different package name:

npm install @heroicons/vue

<template>
  <div>
    <BeakerIcon class="size-6 text-blue-500" />
    <p>...</p>
  </div>
</template>

<script setup>
import { BeakerIcon } from '@heroicons/vue/24/solid'
</script>

If you would rather not add a dependency at all, the README's basic usage is to copy the SVG source from heroicons.com and inline it. That markup carries `fill="none"`, `stroke="currentColor"` and `stroke-width="2"` on the `svg` element, which is what makes the icon follow the text color without extra CSS.

Where Heroicons stops: frameworks, icons and the contribution policy

The most consequential limitation is stated plainly in the contributing section. The maintainers are "currently only interested in contributions that fix bugs", and the README adds, in bold, that contributions for new icons or for other frameworks such as Svelte or SolidJS are not accepted. The suggested alternative is to publish your own icon library and your own framework packages. So if your stack is Angular, React Native, Figma or Svelte, the project itself is the wrong place to look; the search phrases around those frameworks do not correspond to anything Heroicons ships.

A second constraint is that the set is curated, not comprehensive. There is no request process for a missing glyph. Teams that need domain-specific icons will end up maintaining a second set alongside Heroicons, which means two naming conventions and two color conventions in one codebase.

There is also a bundle-size consideration that the README does not discuss. Importing named components is the documented pattern, and whether unused icons are tree-shaken depends on your bundler and on how the package is consumed, not on anything Heroicons documents. Treat per-icon import cost as something to measure in your own build rather than assume.

Heroicons compared with Lucide, and when to pick the other one

Lucide is the comparison people search for, and the difference is structural rather than cosmetic. Heroicons is a fixed, hand-curated set organized into four size and style variants, maintained by the Tailwind CSS team, with no new-icon contributions accepted. Lucide is a fork lineage of Feather with a much larger catalogue and an open contribution model, which means it grows with requests and covers frameworks beyond React and Vue through community packages.

That changes the decision. If your icons must match a Tailwind-styled design system and you want a small, stable, deliberately limited set, Heroicons is the tighter fit: fewer choices, consistent grid, first-party React and Vue packages. If you need a specific glyph that does not exist in Heroicons, or you are on a framework the project declines to support, Lucide's contribution path is the one that can actually respond. The trade-off runs both ways: a larger catalogue is less uniform, and a set that accepts everything is a set where visual consistency is nobody's job in particular.

A third option is no library at all. Copying the SVG from heroicons.com into your markup is a legitimate production choice for a handful of icons, and it removes the dependency entirely. It stops being reasonable once you need dozens of icons, because you lose the naming consistency that the packages enforce.

Maintenance cadence, versioning and the MIT licence

The repository is not archived, and the last push was on 2026-05-12. The most recent release listed is v2.2.0 from 2024-11-18, preceded by v2.1.5 and v2.1.4 in mid-2024. So the pattern is long gaps between tagged releases with repository activity in between, which fits a project whose scope is deliberately closed: there is no stream of new icons to ship, only fixes and build changes.

For upgrade planning, that is mostly good news. The package version in `package.json` tracks the release, and the public surface is import paths plus icon names. The risk of an upgrade is therefore not behavioral but nominal: an icon renamed or moved between variant folders would break an import, and the repository includes a `lint` script (`node ./scripts/verify-names.js`) that suggests naming is treated as a checked invariant rather than an accident.

The licence is MIT, declared in both `package.json` and the LICENSE file. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. Two practical notes, not legal advice: keep the LICENSE text with any redistributed copy, and if you vendor individual SVGs into your own repository, the notice requirement still applies to those files. If you fork the icons into your own library, as the contributing section effectively encourages, you are responsible for carrying the licence forward.

Editorial conclusion

Adopt Heroicons if you are building a React or Vue interface and want icons that inherit the current text color and size through ordinary CSS classes, with no runtime icon-font dependency. Do not adopt it if you need Angular, React Native, Figma or Svelte support from the project itself, or if you need icons outside the shipped set: the README states that new icon contributions are not accepted. Before committing, verify the exact import path for the size and style you want, since outline exists only at 24x24 and the solid variants at 16, 20 and 24, and check the icon name against the package listing on UNPKG rather than guessing the camel-case form.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tailwindlabs/heroicons on GitHub