Blade Health Icons Laravel Package

Getting Started

• Install with composer require troccoli/blade-health-icons. No service provider registration or publishing is needed — the icon set is auto-registered with blade-icons.
• Version gate first: v6.0.0 supports Laravel 13 (and whatever Laravel 12/PHP floor it was tested against) and drops Laravel 11. If the app is still on Laravel 11, pin ^5.0 and defer this upgrade; if you're planning the Laravel 11 → 12/13 hop anyway, do the framework upgrade first and let this package follow.
• Where to look first: config/blade-icons.php (only present if you've published it) shows the set name and prefix that determines the Blade tag. The icon names themselves are the Health Icons file names; browse the package's SVG source folder under vendor/troccoli/blade-health-icons/ or the upstream catalogue at healthicons.org before guessing a name.
• First use case: replace an ad-hoc emoji or copy-pasted inline <svg> in a status pill with a component, e.g. <x-health-icon-heart class="h-5 w-5 text-red-600" />. Attributes fall through to the root <svg>, so Tailwind sizing/colour just works. If your install registers the set as a component namespace instead of a flat prefix, the equivalent is <x-health-icons::heart /> — verify against the registered config once, then standardise.

Implementation Patterns

• Wrap it, don't sprinkle it. Create one <x-ui.health-icon :name="..." :variant="'outline'" /> (or an enum-backed <x-ui.status :status="..."/>) that owns the mapping from your domain vocabulary (critical, allergy, blood-type, pregnancy) to icon names. When v7 renames a glyph, you edit one file instead of grepping 40 views.
• Dynamic names from data. Health icons are usually chosen per-record (condition type, allergy, department). Either build the tag string and render with <x-dynamic-component :component="'health-icon-'.$record->icon" />, or use the blade-icons helper: {{ svg('health-icon-'.$record->icon, 'h-6 w-6 text-slate-500') }}. The helper is the better fit inside loops and @foreach table cells.
• Enum + match mapping. Pair with a PHP enum (Condition::Diabetes->icon()) so the mapping is unit-testable and available to both Blade and JSON resources.
• Variant handling. Health Icons ships outline and filled variants; pick a convention (outline = neutral, filled = selected/active) and encode it in the wrapper so tabs/toggles stay consistent.
• Deploy pipeline: add php artisan icons:cache to your deploy script if you render many icons across pages, and php artisan icons:clear in local/CI scripts. Both are blade-icons commands and are safe no-ops when nothing is cached.
• Accessibility convention: decorative icons get aria-hidden="true"; meaningful ones get role="img" plus an aria-label passed through the component. Bake this into the wrapper so nobody has to remember it.
• Livewire / Alpine: these are pure server-rendered SVGs — no JS payload, no hydration concerns, so they drop into Livewire components and Blade partials with no coordination. They are not a good fit for HTML email/PDF output; inline SVG support is patchy there, so keep a text/emoji fallback for mailable views.

Gotchas and Tips

• The v6 upgrade is a Laravel-version upgrade, not a code change. Symptoms after a careless composer update are a solver conflict, not a runtime error. Diagnose with composer why-not troccoli/blade-health-icons 6.0.0. If you maintain packages/apps across both Laravel 11 and 12/13, use a union constraint (^5.0 || ^6.0) rather than forcing everyone forward.
• Icon cache vs. package upgrades: after bumping the package, cached icon manifests don't know about new glyphs. Clear/re-warm the cache in the same deploy step that runs composer install, otherwise brand-new icons silently render as nothing.
• Typos fail late. The icon name is a string, not a symbol — a misspelled or wrong-variant name shows up as a missing/empty SVG or a "component not found" error at render time, often on a rarely visited page. Assert on your wrapper in a feature test so a bad mapping fails CI.
• Class merging surprises. blade-icons merges your class attribute with defaults; the resulting specificity can leave icon sizing at the default w-6 h-6 when you expected your own. When overriding, pass the full size set (h-5 w-5) from the wrapper rather than relying on a single utility to win.
• Tailwind purging: literal class strings inside Blade components are picked up fine, but class names assembled at runtime ("text-{$severity}-500") get purged. Safelist the severity palette or use a match returning full literal class strings.
• Colour comes from currentColor. Health Icons SVGs inherit colour, so text-* (or a parent's colour) drives them — don't try to restyle fills with fill-* on the component unless the specific glyph is fill-based, and check outline vs. filled before theming.
• Overriding a glyph: publish the blade-icons config and point an additional set path at your own SVG directory, keeping the file name identical, for the rare icon you need to adapt (brand mark, local signage). This is the intended extension point — avoid editing files inside vendor/.
• Snapshot tests are brittle. Version bumps can change SVG markup (path data, viewBox, aria attributes). Assert on a stable wrapper attribute (data-icon="heart") you control rather than asserting raw SVG output.