Weave Code
Icons Laravel Package
artisanpack-ui/icons
An extensibility layer for registering custom SVG icon sets in Laravel, built on blade-ui-kit/blade-icons and integrates with Livewire UI Components. Configure sets via config or events, with no hardcoded icons, minimal memory use, and Font Awesome Pro support.
An extensibility layer for Blade Icons that enables flexible registration of custom SVG icon sets via config or events.
Frequently asked questions about Icons
- How do I install artisanpack-ui/icons in a Laravel application?
- Run composer require artisanpack-ui/icons, then publish the configuration with php artisan vendor:publish --tag=artisanpack-package-config. That creates config/artisanpack/icons.php, where you declare each set's path and prefix. There is no Node build step, asset publishing, middleware, or route registration, so setup is limited to those two commands plus dropping your SVG files into the configured directories.
- How do I register a custom SVG icon set through the config file?
- Add an entry under the sets key in config/artisanpack/icons.php with a path pointing at the directory holding your SVGs and a prefix used in Blade. For example, a path of resource_path('icons/fontawesome-pro') with the prefix fa lets you render x-icon-fa-home in a template. The SVG filename becomes the icon name after the prefix, so home.svg resolves as fa-home.
- How can another package register its own icon sets without touching the host app config?
- That is the event-driven path the package is built around: hook into the ap.icons.registerIconSets filter with addFilter() and call IconSetRegistration::addSet($path, $prefix). It lets internal or third-party packages ship their own icon directories that merge into Blade Icons at boot. Because the hook name and the addFilter helper have changed across releases, pin the version you build against.
- Which Laravel versions does artisanpack-ui/icons support?
- The package targets recent Laravel releases, with a Laravel 12 and 13 floor, so teams still on Laravel 10 or 11 cannot adopt it without upgrading first. Check the composer.json constraints of the specific version you install before planning adoption. If you are pinned to an older major, registering sets directly with blade-ui-kit/blade-icons is the practical alternative.
- Does the package include Font Awesome Pro icons or any bundled icon set?
- No. Since the 2.0 rewrite it ships zero hardcoded icons and no bundled Font Awesome webfont; it only registers path and prefix pairs pointing at SVGs you supply. That keeps memory use low and makes premium sets like Font Awesome Pro usable, but procuring the assets and policing their redistribution terms is entirely your responsibility.
- What does artisanpack-ui/icons add over calling BladeUI\Icons\Factory::add() in a service provider?
- Functionally it does much the same thing: it is a thin adapter that populates Blade Icons with path and prefix pairs so components resolve to local SVG files. What it adds is the published config convention and the ap.icons.registerIconSets hook, so other packages can contribute icon sets without editing the host application. If you do not need that hook, roughly thirty lines in AppServiceProvider achieves the same result with one less dependency.
- Why do I get CannotRegisterIconSet::prefixNotDefined when rendering icons?
- That exception originates in BladeUI\Icons\Factory::add() when a set is registered without a prefix key, and it has occurred in this package's own registration path in a prior release. Because icon resolution runs inside Blade component rendering, the failure can escalate to application-wide render errors, including in apps that also run owenvoke/blade-fontawesome. Confirm every set in config has both path and prefix, and stay on a patched version.
- How should I test that my icon sets resolve correctly?
- Render a component such as x-icon-fa-home in a feature test and assert the response contains the expected SVG markup, plus assert how a missing icon behaves. Since the package is a registration shim, the valuable tests are integration-level: boot the provider, resolve the Blade Icons factory, and verify the registered prefixes. Add a specific regression test for the prefix key, because a missing prefix escalates into application-wide render failures.
- Is artisanpack-ui/icons safe to use in production?
- Architecturally it is a simple, low-ceremony package that does what it claims, but it currently has no stars, no dependents, and no visible contributor base, and its hook API changed across 2.0, 2.1, and 2.2. If you adopt it, pin exact versions, wrap registration in your own service class so it can be swapped out, and keep a fork-or-replace plan ready. Many teams will reasonably decide that direct Blade Icons registration is the lower-risk option.
- What dependency does artisanpack-ui/icons pull in, and what happens if the hook API is removed?
- It requires artisanpack-ui/hooks, a bespoke successor to tormjens/eventy that exposes a global addFilter() helper, so you are adopting a second young package into the graph. Release 2.2 renamed the hook string and kept an alias for the old name, with removal scheduled for the next major. That means an upgrade can break icon sets registered by other packages without any change on your side, so treat the hook name as part of your pinned contract.
Weaver
How can I help you explore Laravel packages today?