Filament Only Icon Display Laravel Package

Getting Started

filament-only-icon-display is a small Filament add-on that lets you render UI elements — typically action buttons, links, or table/navigation items — as an icon only, with the text label suppressed. v0.2.0 is a documentation-only release (docs enhancements plus disclaimers), so there are no code changes to adopt; treat it as the first credible baseline for evaluating the package.

Where to look first, in order:

1. README.md — v0.2.0's whole point. Read it before installing; the newly added disclaimers set expectations around support and maintenance, which matters for production use.
2. composer.json — confirm the Filament major version constraint (v3 vs v4), PHP version, and whether it is a plugin (filament/plugin) or a plain Blade/utility package.
3. src/ — identify the public surface: a Blade component, a macro/trait, an enum, or a helper class. That tells you how much of your panel you can convert without custom views.
4. Any resources/views directory — if views are publishable, that is your styling extension point.

Minimal first use case: install into a Filament panel and take one existing table action or header action that already has an ->icon() set, then apply the package's icon-only treatment to it. Verify it renders correctly in light/dark mode and at mobile breakpoints before rolling it across the panel. Because the package is narrowly scoped, prove it on a single resource page first.

If the README's new disclaimers indicate limited maintenance, decide up front whether this is a "use in one or two places" convenience or a panel-wide convention. For a package this small, a fallback is cheap to write yourself.

Implementation Patterns

Single-action conversion. The common workflow is per-element opt-in: keep your existing Filament action definitions and apply the icon-only behaviour only where horizontal space is at a premium — table row actions, header actions, bulk actions. Leave form submit buttons and destructive confirm modals labelled; icon-only UI there is a usability regression.

Build a panel convention helper. If you adopt the package broadly, wrap it. Create your own App\Support\Filament\IconOnly helper or a set of static factory methods that call the package, so that if it is abandoned (see the new disclaimers) you swap one class rather than editing dozens of resources.

Navigation and grouping. Icon-only makes the most sense in Filament navigation groups and collapsed sidebars, where Filament already hides labels responsively. Test whether the package composes cleanly with Filament's own ->collapsed()/isCollapsible() behaviour rather than fighting it — double hiding or double tooltips are the likely failure modes.

Composition with tooltips. Always pair icon-only output with a visible-on-hover affordance (->tooltip() on the Filament action, or title/aria-label in the Blade layer). Make this part of your helper so it is not forgotten per call site.

Testing pattern. Filament actions live in Livewire components. Assert with a Livewire test that the label text is absent and the icon class/identifier is present, e.g. assertDontSee('Delete') alongside the icon assertion. This is what stops a future package bump from silently reintroducing labels.

Version pinning. Given a docs-and-disclaimers release as the second tag, pin to ^0.2 and read the changelog on each bump. There is no meaningful API stability signal at 0.x.

Gotchas and Tips

• This release changes no behaviour. v0.2.0 is documentation and disclaimers only. Do not schedule an upgrade window; do read the new disclaimers, as they may set support/liability expectations you need to record in your dependency decision log.
• Accessibility is the main risk. Icon-only controls without aria-label or a tooltip are unreachable for screen readers and ambiguous for everyone else. Filament's own ->hiddenLabel() already has known accessibility caveats; verify what the package does on top of it rather than assuming it adds labelling.
• 0.x semver. Expect breaking changes in minor bumps. Wrap usage behind your own helper (see above) and pin exact versions in composer.json if the package is in a client-facing panel.
• Plugin vs. manual registration. Check whether the README instructs ->plugin() registration in your PanelProvider or a service-provider register(). Registering a Filament plugin as a normal package provider (or vice versa) is the most common "it does nothing" failure — confirm the class implements Filament\Contracts\Plugin before guessing.
• View publishing and asset caching. If the package ships publishable views, publish them (vendor:publish --tag=...) rather than editing vendor files, and run php artisan filament:assets / view:clear after changes. Stale compiled views and cached assets explain most "my override isn't applied" reports.
• Dark mode and theme colours. Icon-only elements rely entirely on the icon's colour for affordance. Check text-danger, text-gray-400, and disabled states in both themes — a greyed icon on a grey background is invisible.
• Where icon-only is wrong. Destructive bulk actions, confirmation modals, primary create buttons on empty states, and anything with more than one similarly-shaped icon in a row. Keep those labelled; use this package as an exception, not a default.
• Fallback plan. The implementation surface is small enough that a Blade partial plus ->hiddenLabel() and a ->tooltip() replicates most of it. Budget an hour for that fallback rather than accepting a hard dependency on a single-maintainer 0.x package in a long-lived panel.