Weave Code
Blade Heroicons Laravel Package
blade-ui-kit/blade-heroicons
Blade Heroicons lets Laravel Blade views render Heroicons as simple SVG components, e.g. , with support for classes, inline styles, configuration, and icon caching via Blade Icons. Install with composer require blade-ui-kit/blade-heroicons.
Blade Heroicons is a Laravel package that brings the complete Heroicons SVG icon set directly into your Blade views. Icons are rendered as self-closing Blade components, making them simple to use and composable alongside your existing markup.
<x-heroicon-o-arrow-left class="w-6 h-6 text-gray-500"/>
Features
- Access all Heroicons via clean
<x-heroicon-*>components - Apply default or custom CSS classes and inline styles
- Built on Blade Icons for extra flexibility
- Publishable config for default classes and attributes
- Compatible with icon caching for better performance
Frequently asked questions about Blade Heroicons
- How do I install blade-ui-kit/blade-heroicons in a Laravel app?
- Run composer require blade-ui-kit/blade-heroicons in your project root; the service provider is auto-discovered, so there is nothing to register by hand. There are no migrations, environment variables, or route changes to run afterwards. Two optional steps remain: publishing the blade-heroicons.php config file for default classes and attributes, and publishing the raw SVGs if you also want to use them as image files.
- Does Blade Heroicons support Laravel 10, 11, 12, and 13?
- The package requires PHP 8.0 or higher and Laravel 9.0 or higher, and support has been added release by release: Laravel 11 in 2.3.0, Laravel 12 in 2.6.0, and Laravel 13 in 2.7.0. Both the 1.x and 2.x lines are maintained with Laravel 11 through 13 support, which helps teams stuck on an older major. Choose a major deliberately and avoid floating on a wildcard constraint, because an unexpected major bump can change icon names underneath you.
- How do I use Heroicons in a Laravel Blade view?
- Icons are self-closing Blade components, so <x-heroicon-o-arrow-left/> compiles straight to an outline arrow-left SVG with no JavaScript involved. Pass utility classes with the class attribute, for example class="w-6 h-6 text-gray-500", and inline styles work the same way. The @svg() directive from the underlying Blade Icons package is also available when you need to resolve an icon inside a template.
- What is the difference between the heroicon-o, heroicon-s, heroicon-m, and heroicon-c variants?
- Blade Heroicons exposes roughly 1,200 Heroicons SVGs across four sets, each with its own component prefix: o for outline (24px, the usual choice for navigation and actions), s for solid (24px, for active or selected states), m for mini (20px, for compact buttons and list rows), and c for micro (16px, for dense tables). The prefix in the component name is what selects the size and weight, so the variants map directly onto UI density. Mixing them on one screen is fine, but keep the mapping consistent so the visual rhythm stays predictable.
- How do I set default classes or attributes for every Heroicon?
- Publish the configuration file with php artisan vendor:publish --tag=blade-heroicons-config, which creates config/blade-heroicons.php. From there you can declare default classes and default attributes that Blade Icons applies to every rendered icon, so a standard size or colour lives in one place instead of being repeated in every view. Most teams commit this file so the whole codebase shares the same defaults, and it is the first thing to check when icons suddenly look different.
- How do I enable icon caching for Blade Heroicons in production?
- Blade Heroicons renders through Blade Icons, and that underlying package is where caching lives; the readme explicitly recommends enabling it. Cache the compiled icon set as part of your deploy and clear it whenever config or icon names change, otherwise stale entries can keep resolving icons you thought were removed. Test the invalidation step on staging before relying on it, and remember that caching also affects how quickly a newly added icon appears.
- Are Heroicons accessible by default, and how do I add aria labels?
- No, accessibility is opt-in. Components emit decorative SVGs by default, so purely visual icons should get aria-hidden="true", while meaningful icons need role="img" plus an aria-label or adjacent visually hidden text. Because these are ordinary Blade components, you can centralise the pattern in your own wrapper component or enforce it with a lint rule across teams. Treat WCAG conformance as something your codebase guarantees, not something the package does for you.
- Can I use the raw Heroicons SVGs outside of Blade components?
- Yes. You can publish the package's raw SVG files and reference them directly, for example inside an img tag or as a background asset, which is handy for emails and non-Blade contexts. Be aware that this creates a second icon pipeline alongside the Blade components, and the two can drift if they are not both updated on upgrade. Decide whether you need components, raw files, or both, and document the choice so nobody adds yet another source of truth.
- What happens if Heroicons renames icons in a future major release?
- It has happened before: package version 2.0.0 moved to Heroicons v2, dropped PHP 7.4 and Laravel 8, and renamed icons. A component name that no longer resolves fails at render time rather than at install time, so an upstream major can surface as a runtime error in a view nobody tested. Pin the package to a known major, keep a registry of the icon names your app actually uses, and add a test that renders them so renames fail in CI instead of production. The same logic applies to the transitive blade-icons dependency, which is worth pinning and reviewing on its own release cadence.
- How can I test that every Heroicon component still resolves after an upgrade?
- Write a feature test that loops over your application's list of icon names and renders each component with Blade::render or a small Blade view, asserting a successful response. Compare that list against the icons shipped in the package's resources/svg directory after every upgrade to spot removals that would break views and additions you may want to adopt. It is also the right place to assert that defaults from blade-heroicons.php still apply. This single test protects you against both upstream icon renames and regressions in blade-icons.
Weaver
How can I help you explore Laravel packages today?