Heroicons: Copy the SVG, or Import the Component, on Purpose
Heroicons are an SVG icon set you either copy from the project or import through the packages the project documents. What the set is, and how the files are licensed, is written on the README and the license file. This page does not restate that license, a catalog count, or a contribution policy. Open those pages. This is a production note, not legal advice and not a promise about rankings.
Browse names on the project site. If the icon has to follow a layout, read responsive icons after you decide how this symbol enters the page.
What to copy from the Heroicons README
The README is the list of inclusion methods. Read it for the basic SVG example and for the React and Vue sections. Use the example’s attributes as written on that page. Do not type a viewBox or a stroke from memory, and do not recolor path data when the example tells you to style the element with CSS color.
The same page is where you read whether the project wants new icons or new framework wrappers. Follow that section instead of a paraphrase. If a symbol is not in the set, draw it in your own system. Do not hide a hand-drawn path inside the vendor folder, or the next upgrade will overwrite it or block the upgrade.
React and Vue, only along the documented paths
When the app is React, the README names the package and the import. Copy that import, including the component name shape it shows. The example name on that page is the pattern. The README also points at a place to browse names. Use that browse page when you are not sure a name exists. Do not invent an entry point.
Vue is a separate section of the same README, with its own package name and its own entry points. Copy from that section. A tutorial that shows a different path is not the README. Check the README before the path lands in the project.
Pick one entry point per control and write it in the component. An outline import beside a solid import looks like two families. The README lists the entry points so you can choose. The choice belongs in the component, not in whichever import the last file happened to use.
How to use Heroicons without forking the set
Prefer the package import when the app is React or Vue and you want the icon to update with the package. Prefer one copied SVG when you need a single symbol and no dependency, or when you are not in those frameworks. A wrapper you publish for another framework is your project. Read the README’s note on other frameworks before you describe that wrapper as theirs.
Keep the viewBox that arrived with the file. The sample viewBox is on the README. Size the icon with CSS. If you need a different master, import the entry point the README names for it. Do not scale one file and call it the other master.
Color comes from the control when the file is set up the way the sample shows. If a paste strips attributes, check that the paint survived. A hardcoded color will not follow the theme. Put the color back the way the sample has it, or stop pasting and use the package.
Name the control separately. The icon is a picture. A button that renders only an icon still needs an accessible name in your markup. Pair this with accessibility guidelines when the control is icon-only.
What not to change
Do not edit the path to match another set and still call the result Heroicons. Once you change the drawing, you are maintaining a fork. Before you redistribute a changed file, read the license file. This article does not summarize it.
Do not pin a blog’s icon list as the catalog. The site is the catalog. Import from the path the current README gives, and let the build fail if a name is gone, instead of shipping a silent empty component.
Tomorrow, install the package only if the app is React or Vue. Import one icon from an entry point copied off the README, render it in a button that has a text name, and change the button’s text color. If the stroke follows, you are using the sample’s contract. If you only needed one SVG, copy that file from the site and skip the package. Either way, leave the viewBox alone.
When a teammate asks for a different framework, point them at the README before anyone wraps the files. A local component that inlines the SVG you copied is a small wrapper you own. Own that wrapper. Do not pretend it is an official library.
Store the chosen entry point in the component name or a short comment. A folder of mixed imports will not match in a toolbar. The files agree with each other inside the set. The agreement survives only if the app picks one import path per surface and sticks to it.
Review the button at the size the class sets, not at the artboard. If the outline looks thin when it is large, switch to the solid entry point the README already lists. Do not thicken the stroke in the vendor file. Change the import. Leave their drawing intact.
Keep vendor files out of the hand-edited icon folder. A copied SVG can live next to the component, with a comment that names the source and the day you copied it. The package install belongs in the dependency file. A designer export dropped into the vendor folder will be overwritten, or it will block the upgrade.
If two entry points disagree about what a symbol means, look at both on the site before you pick. A name can exist in one and not the other. The import will fail, or it will resolve a different picture than the one you discussed. Match the import to the folder you named in the comment.
After the color check, tab to the button. The icon can be ignored by assistive technology when the visible label is the name. If you remove the label later, put the name on the button in the same change. A library upgrade will not notice that you deleted the label. The picture and the name travel as a pair.
Write down the day you copied a loose SVG. The package records its own version. A loose file does not. When someone asks why the button does not match the site, the comment should say which file you copied and from where. Heroicons stay easy to upgrade when the only edited file is your component, and the vendor file is still the one the README describes.
If a sanitizer removes the SVG attributes, the icon may become a filled shape or an invisible one. That is a paste problem, not a reason to redraw. Put the sample’s attributes back, or render the component from the package so you are not pasting markup by hand. Then look at the button again. The check is the color of the stroke and the name of the control, nothing else.
