blade-heroicons: Heroicons as Blade components in Laravel

One package, four icon sizes, and the naming convention that carries them

blade-heroicons is a package to easily make use of Heroicons in your Laravel Blade views. The icons themselves come from the Heroicons project, originally developed by Steve Schoger and Adam Wathan, and a full list of the available icons lives in the SVG directory in the resources folder of this repository, with a preview at heroicons.com.

What the package adds is a naming convention that maps the four Heroicons styles onto Blade component names, and the convention is the thing worth learning. The outline style is the default, so an outline arrow-left is x-heroicon-o-arrow-left.

<x-heroicon-o-arrow-left/>

The solid variant uses s, the mini uses m and the micro uses c, so the same arrow in each style is x-heroicon-s-arrow-left, x-heroicon-m-arrow-left and x-heroicon-c-arrow-left.

<x-heroicon-s-arrow-left/>

<x-heroicon-m-arrow-left/>

<x-heroicon-c-arrow-left/>

The reason the variant is in the component name rather than an attribute is that the four styles of a given icon are genuinely different drawings, not one drawing recoloured. A micro arrow and an outline arrow have different silhouettes, and picking between them at the call site is a decision about the design, not about the colour. Putting the style in the name makes that decision explicit at every use site rather than hiding it behind a default.

The package is MIT licensed with a LICENSE.md file, the primary language is PHP, and the last push to the repository was on 2026-06-22, with release tags 1.7.0 from 2026-05-20, 2.7.0 from 2026-03-17 and 1.6.0 from 2025-06-27.

Attributes go on the component, and the svg directive is the escape hatch

Once the component exists, the rest is ordinary Blade attribute handling, with two routes offered.

The component route passes classes as you would expect on any HTML element.

<x-heroicon-o-arrow-left class="w-6 h-6 text-gray-500"/>

Inline styles work the same way.

<x-heroicon-o-arrow-left style="color: #555"/>

The second route is the @svg directive, which takes the icon name and then the same kinds of arguments.

@svg('heroicon-o-arrow-left', 'w-6 h-6', ['style' => 'color: #555'])

That is a useful escape hatch for cases where a Blade component does not fit, such as when you need the icon inside a string that is generated rather than written in a template.

Underneath, the package is not doing anything clever. Blade Heroicons uses Blade Icons under the hood, and the README points at the Blade Icons readme for additional functionality, and also recommends enabling icon caching with this library.

That last recommendation is the one operational detail to carry into a real application. The icons are SVG files, and a Blade component that reads a file from disk on every render is a file read per icon per render. Caching turns that into a compiled or memoised result. In a page with a hundred icons, the difference between reading a hundred files and reading none is the difference between a page that feels slow and one that does not.

The dependency relationship is also why the package is thin. It contributes the Heroicons asset set, the component naming and a config file, and everything else comes from Blade Icons.

Publishing the config and the raw SVG assets

Two things can be published into your application, and they serve different purposes.

The first is the configuration file, which the README calls blade-heroicons.php, and it carries the Blade Icons features such as default classes and default attributes.

php artisan vendor:publish --tag=blade-heroicons-config

The second is the raw SVG assets. If you want the icons as files rather than as compiled components, you publish them with the force flag.

php artisan vendor:publish --tag=blade-heroicons --force

After publishing, the files are available under a vendor path in your public directory and are referenced with an ordinary image tag.

<img src="{{ asset('vendor/blade-heroicons/o-arrow-left.svg') }}" width="10" height="10"/>

The forced flag is worth pausing on, because the tag used for the assets is also the tag used for the config, and publishing without the flag will not overwrite what is already there. The config file is something you own once published, and the assets are something you would rather not own at all.

There is also an upgrade guide, in UPGRADE.md, which the README says to refer to when updating the library. Given the release history, with a 1.7.0 and a 2.7.0 in the same year, the upgrade guide is the place to look before a major version change.

The top level of the repository matches this structure: a src/ directory with the PHP, a resources/ directory holding the SVG assets, a config/ directory with the publishable config file, tests/ with a phpunit.xml.dist, a composer.json, a package.json, an art/ directory with the social card image, and the usual CHANGELOG.md, SECURITY.md and LICENSE.md files.

The npm dependency is where the icon set comes from

The package.json in the repository is small and it explains something that is otherwise invisible in a Composer package.

{
  "private": true,
  "dependencies": {
    "heroicons": "^2.2"
  }
}

So the Heroicons SVG files are pulled from npm at build time rather than being committed into the repository, and the package is private because it exists only to serve that build step. The version constraint is ^2.2.

The practical consequence is a two-toolchain dependency for a package whose consumer side is pure PHP. To work on the package you need Composer and Node, and the Node side is what keeps the icon set current with upstream Heroicons. A consumer of the published Composer package does not need Node at all, since the assets ship inside the Composer distribution.

That distinction matters when you are deciding whether to depend on this package or on the icon set directly. The package gives you components, a config file and a vendor publishing path; the raw Heroicons set gives you files and nothing else.

The requirements are stated plainly at the top of the README: PHP 8.0 or higher and Laravel 9.0 or higher. Those are the floor, and the current Composer practice of requiring a maintained PHP and Laravel version means the package tracks the same release cadence as the framework.

Installation itself is one Composer command.

composer require blade-ui-kit/blade-heroicons

The package name on Packagist is blade-ui-kit/blade-heroicons, which is worth noting since the repository is driesvints/blade-heroicons and the GitHub organisation in the README badges for the packagist links is blade-ui-kit.

Where blade-heroicons is the wrong tool

The first wrong-tool case is a project that is not on Laravel 9 or later with PHP 8. The requirements are stated as PHP 8.0 or higher and Laravel 9.0 or higher, and there is no compatibility layer for anything older, which is normal for a package that follows the framework's own support window.

The second case is a team that needs a general icon system rather than one icon set. This package is a thin adapter over Blade Icons that adds the Heroicons assets and a naming convention. If you want icons from several libraries, you are better served by Blade Icons itself with several packs registered, and the README points there for additional functionality.

The third case is a design system that does not use Heroicons. The choice of component names embeds the choice of icon set, and the four-style prefix convention is specific to Heroicons, so switching sets means changing every call site or writing a second adapter.

There is a small operational consideration too. The configuration file is published into your source tree, which means your defaults become a file you maintain and can drift from the package defaults, and the recommended icon caching is something you have to turn on rather than get by default. An application that renders a lot of icons and skips caching will feel the difference.

What the package gives you in exchange is very small and very clear: Heroicons as Blade components with a readable name, a config file for shared defaults, and an option to publish the raw assets if you need them as files. The homepage is blade-ui-kit.com/blade-icons, the project is developed and maintained by Dries Vints, and the licence is MIT.

Editorial conclusion

blade-heroicons suits a Laravel application that has already chosen Heroicons and wants them as Blade components rather than inlining SVG or using an icon component library, because the component names are predictable and the variant prefixes are readable in the template. It does not suit a project on a framework other than Laravel, and it does not add anything beyond the icon set, so a team that needs a broader icon library should look at Blade Icons directly. Before adopting, note that configuration is published into a file in your source tree and that the package recommends enabling icon caching, because the raw SVG assets are also publishable and will otherwise be read on every render.

Frequently asked questions

Official sources

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