Hugeicons Flux Laravel Package

Getting Started

Install and you are done for the free tier — no Node, no licence key, no committed files, no build step:

composer require abduns/hugeicons-flux

<flux:icon.hugeicons.home-01 class="size-6 text-zinc-500" />

The components register through Flux's own flux Blade namespace under a hugeicons prefix, so this is a normal Flux icon. Anything you already know about <flux:icon.*> applies immediately: class="size-8" sizes it, text-blue-500 colours it, and the string form works anywhere Flux accepts an icon prop.

Where to look first. The bundled icon set is the canonical name index — not the Hugeicons website, and not a guess:

ls vendor/abduns/hugeicons-flux/resources/views/flux/icon/hugeicons/ | grep -i search

Names are kebab-case derivations of Hugeicons identifiers (Home01Icon → home-01, AiSearch02Icon → ai-search-02). Grep before you write the tag; there is no compile-time check, so a wrong name is a render-time failure.

First use case. Do not start by sweeping the codebase. Swap one icon in an existing view — the account dropdown in your topbar, or a single flux:navlist.item — and confirm it renders at the right size and colour alongside Flux's built-in icons. That five-minute check validates the registration, the naming convention, and your team's sizing habit in one go. Then extend to the navlist and buttons:

<flux:navlist.item icon="hugeicons.dashboard-square-01">Dashboard</flux:navlist.item>
<flux:button icon="hugeicons.calendar-03" variant="primary">Schedule</flux:button>

If you use an AI agent day-to-day, the bundled Laravel Boost skill is the second thing to read. It encodes the exact workflow — resolve name by grep, decide whether a build is needed, build one icon — and prevents an agent from dumping the entire set into your repo:

php artisan hugeicons:boost-skill          # publishes to .ai/skills for customization
php artisan boost:install                  # or: boost:update --discover

Implementation Patterns

Treat hugeicons.* as a string contract, not just a tag. The highest-leverage pattern is that icon="hugeicons.{name}" is data, not markup. That means icon names can come from config, a NavItem data object, a database column, or a match statement:

<flux:navlist.item :icon="'hugeicons.' . $item->icon">…</flux:navlist.item>

This is what makes the package worth adopting: you can build a navigation definition once and render it in a sidebar, a mobile drawer, and a command palette without three separate icon systems.

Default to the free tier and stay there. Stroke Rounded covers the overwhelming majority of product UI needs. Every day you do not touch variant, you are shipping from vendor/ with zero repo surface area. Reserve Pro styles for a deliberate design decision — a marketing page hero, a pricing table — not for routine UI.

Use the hybrid variant prop as a design-system bridge. It accepts real Hugeicons style names and Flux's own aliases, which lets you standardise on Flux vocabulary in application code while still reaching Pro styles:

<flux:icon.hugeicons.search-01 variant="solid-rounded" class="size-8 text-amber-500" />

A practical convention: use variant="micro" for inline text icons and the default for nav, so the vocabulary stays Flux-native and a future migration away from Hugeicons is a find-and-replace on the prefix rather than a rewrite.

Pro is a build-pipeline change, not a code change. The workflow in full:

# .npmrc — commit this, it holds no secret
@hugeicons-pro:registry=https://npm.hugeicons.com/
//npm.hugeicons.com/:_authToken=${HUGEICONS_PRO_LICENSE_KEY}

export HUGEICONS_PRO_LICENSE_KEY="…"      # present at npm install time only

npm install --save-optional \
  @hugeicons-pro/core-stroke-rounded \
  @hugeicons-pro/core-solid-rounded

php artisan hugeicons:build home-01 search-01   # named icons only

hugeicons:build {name} writes resources/views/flux/icon/hugeicons/{name}.blade.php into your app. Flux resolves your app's resources/views/flux path before the package path, so the generated file overrides the bundled free version. That is the extension mechanism, and it also means generated files are repo artefacts: commit them, review them in PRs, and treat them as the project's declared Pro icon inventory.

Wire the secret once, in CI. The key is needed by npm ci, not by hugeicons:build. That distinction matters for build caching — you can run php artisan hugeicons:build in a step that has no access to the licence key:

- run: npm ci
  env:
    HUGEICONS_PRO_LICENSE_KEY: ${{ secrets.HUGEICONS_PRO_LICENSE_KEY }}

Add one cheap smoke test. A Blade render test over a representative few icons (home-01, a nav icon, one Pro variant) catches the two failure modes that are otherwise invisible: a renamed icon and a Pro style that silently fell back.

Gotchas and Tips

Variant fallback is silent. If a requested style is not installed, the component falls back to stroke-rounded and renders happily. Nothing errors, nothing logs. This is the single most likely way to ship a page that looks subtly wrong: your Pro build was incomplete on CI, and every solid-rounded icon is quietly outlined. Verify by checking the built file exists and inspecting the rendered SVG, not by looking at the page and hoping. Consider a CI check that greps committed components for the variants you expect.

Never run hugeicons:build with no arguments. It dumps all ~6,100 icons into resources/views/flux/icon/hugeicons/ in your repo. Always pass names. If it happens, git status will make it obvious — check before committing.

Version skew in the docs. The README claims PHP 8.2+ and Laravel 11+; the v1.0.5 changelog says PHP 8.2 was dropped and Pest v4 adopted, and CI references Laravel 13. Treat composer.json constraints as authoritative, not the README compatibility table. Pin at minimum ^1.0.1 — 1.0.0 shipped with the prefix hugeicon instead of hugeicons, so the tag in 1.0.0 was simply broken.

The licence field is NOASSERTION while the README and LICENSE.md claim MIT, and the package bundles 5,100+ third-party icon files. If this is going anywhere near a commercial codebase, get that resolved and confirm the free-set terms in writing before it becomes load-bearing. Release metadata is also future-dated — do not treat published signals as verified.

Names fail at render time, not before. There is no autocomplete and no compile check. Build the grep into your workflow (and into your agent skill); it is a one-second habit that replaces every "why is my icon blank" debugging session.

Debugging checklist, in order: does the file exist (test -f resources/views/flux/icon/hugeicons/{name}.blade.php)? Does the bundled file exist in vendor/? Is the @hugeicons-pro/core-* package actually in node_modules/@hugeicons-pro/? Did you php artisan view:clear after a rebuild? The deferred service provider means registration happens late by design — if a component genuinely will not resolve, view:clear and a fresh composer dump-autoload clear 90% of these.

Extension points worth knowing. The deferred service provider is deliberate, so you can override registration in your own provider rather than forking. And the app-path override convention means you can hand-edit a generated component — say, to hard-code a specific stroke width — and it will keep winning over the vendor copy. Do that sparingly and comment why, because a re-run of hugeicons:build for that icon will overwrite it.