Iconamic Laravel Package

Getting Started

Iconamic is a Statamic addon that adds an icon picker fieldtype, letting editors choose an icon from a configured set (e.g. Heroicons, Font Awesome, or your own SVG folder) and storing the choice as a simple string handle on the entry.

Version 3.0.0 is the Statamic 6 compatibility release, so the first thing to confirm is your platform:

composer require mitydigital/statamic-iconamic

• Statamic 6 → use ^3.0
• Statamic 4/5 → stay on ^2.2 (do not bump the constraint)

Then publish the config and register a field:

php artisan vendor:publish --tag=iconamic-config

Add an icon fieldtype to a blueprint (e.g. a button set in a Replicator, or a card partial's fields), pick which icon sets are available in the field's config, and save an entry from the CP. Look first at:

1. config/iconamic.php — where icon sets, paths and labels are defined.
2. The fieldtype's rendering in your Antlers templates (check the README for the exact output tag/helper this version exposes) — this is the piece most likely to differ between major versions.

The most common first use case: a "Button" Replicator set where the editor picks an icon and you render it inline next to the label.

Implementation Patterns

Single field, shared partial. Store the icon on the entry, then render it through one partial so sizing/classes stay consistent:

{{ partial:icon :handle="icon" class="w-5 h-5" }}

Inside the partial, output the icon markup and pass through class/attributes. Keeping this centralised means a change to icon sizing is one edit, not fifty.

Replicator / Bard sets. Icon fields shine inside sets — button, feature, callout. Keep the field handle stable (icon) across sets so the same partial works everywhere, and mark it required only where an icon is genuinely mandatory; otherwise editors get blocked on optional UI.

Custom icon sets. Point a set at your own SVG directory in config/iconamic.php rather than vendoring a whole icon library. This keeps the picker fast and the repo small. Group sets by purpose (ui, social, payment) so the picker stays scannable — a 500-icon flat list is a usability failure, not a feature.

Restrict sets per field. Set-level config in the blueprint is your guardrail: a social set shouldn't offer payment icons. Fewer choices, fewer support tickets.

Theming. Inline SVG inherits currentColor, so drive icon colour from CSS/Tailwind text colour rather than storing colour per icon. This keeps content portable across dark mode and multi-site themes.

API/headless usage. The stored value is a plain handle string, so it survives GraphQL/REST output cleanly. If you're rendering headless, resolve the handle to SVG on the front end or expose a resolved field via an augmentation if one is provided in this version.

Gotchas and Tips

This is a breaking major. 3.0.0 exists solely to support Statamic 6 (PR #13). Treat it as a platform-locked upgrade: if your app is on Statamic 4 or 5, pinning ^2.2 is correct and ^3.0 will break the CP fieldtype or fail dependency resolution. Plan the Statamic 6 upgrade and this bump as one deploy, not two.

Upgrade checklist for Statamic 6 apps:

composer require mitydigital/statamic-iconamic:^3.0
php artisan vendor:publish --tag=iconamic-config --force
php artisan config:clear && php artisan view:clear && php artisan stache:clear

Re-publish and diff the config — a major release is the most likely moment for renamed or restructured config keys, and a stale published config is the usual cause of "the picker is empty after upgrade".

Stale icon lists. New SVG files dropped into a set's directory won't always appear immediately. If the picker looks out of date, clear caches (stache:clear, plus any addon cache) before debugging the fieldtype itself.

Inline SVG and escaping. Rendering raw SVG in Antlers requires an unescaped output modifier (|raw) — but only do that for icons from your own configured sets. Never let an editor-supplied upload flow into an icon set, or you've built an SVG/script injection vector (SVGs can carry <script>).

Path and case sensitivity. Icon directories configured with a trailing slash or mismatched case work locally on macOS and fail on Linux CI/production. Verify with a deploy, not just php artisan serve.

Don't store full SVG markup in the field or in a Markdown/Bard field. The handle-only storage is the whole point: swap the icon library later and content still resolves.

Extension points. The two you'll actually reach for are (a) registering additional icon sets in config, and (b) overriding the addon's view to control the emitted markup and attribute passthrough. Reach for (b) before forking the package — forking an addon with a Statamic-version-locked major means you own the next upgrade yourself.

Debugging. If a field renders as an empty string, work down this list: field handle mismatch in the partial → icon set not enabled on that field → SVG file missing/misnamed in the configured path → cached view/config. That ordering catches the vast majority of issues without touching the addon source.