Filament Untitledui Icons Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mckenziearts/filament-untitledui-icons
   

   Add the plugin to your PanelProvider:

   public function panel(Panel $panel): Panel
   {
       return $panel->plugin(UntitleduiIcons::make());
   }
   

2. First Use Case: Replace default Filament icons globally with Untitled UI’s set. No additional configuration is needed beyond registration—all existing icon usages (e.g., Icon::make('heroicon-o-pencil')) will now render as Untitled UI icons.

3. Where to Look First:

   • Filament Icons Documentation for alias compatibility.
   • UntitleduiIcons::make() methods for style customization (e.g., regular()).

Implementation Patterns

Workflows

1. Global Replacement: Register the plugin once in PanelProvider to replace all icons across your Filament admin panel. No per-resource or per-view configuration is required.

2. Style Consistency: Set a default style (e.g., UntitleduiIcons::make()->regular()) in PanelProvider to ensure uniformity. Override styles for specific icons only when necessary.

3. Icon Alias Mapping: Use Filament’s icon aliases (e.g., heroicon-o-pencil) to map to Untitled UI’s equivalent. The package handles the underlying SVG rendering automatically.

4. Dynamic Styling: Override styles for subsets of icons in resource/views or widgets:

   UntitleduiIcons::make()
       ->overrideStyleForAlias('heroicon-o-pencil', 'bold') // Hypothetical style
       ->overrideStyleForAlias(['heroicon-o-trash', 'heroicon-o-eye'], 'outline');
   

Integration Tips

• Theme Compatibility: Test Untitled UI’s styles against your Filament theme (e.g., dark mode). Some styles may require CSS adjustments for contrast.
• Icon Selection: Use the Untitled UI icon explorer to preview icons before implementing. Note that not all Filament aliases may have direct equivalents.
• Lazy Loading: If performance is critical, consider lazy-loading the icon pack via JavaScript (though the package likely handles this server-side).

Gotchas and Tips

Pitfalls

1. Alias Mismatches:

   • Not all Filament icon aliases have equivalents in Untitled UI. Verify compatibility by checking the package’s icon list or testing in a staging environment.
   • Debug Tip: Use dd(UntitleduiIcons::getAvailableIcons()) to list supported aliases.

2. Style Inconsistencies:

   • Untitled UI’s "Regular" style may not align perfectly with Filament’s default icon sizes/colors. Override CSS if needed:

     .filament-icon {
         width: 1em;
         height: 1em;
         color: inherit; /* Ensure color matches Filament’s theme */
     }
     

3. Plugin Registration Order:

   • Register UntitleduiIcons after other icon providers (e.g., FilamentIcons) to avoid conflicts. The last registered provider typically takes precedence.

4. Caching Issues:

   • Clear Filament’s view cache (php artisan filament:cache:clear) if icons fail to update after style changes.

Debugging

• Missing Icons: Use browser dev tools to inspect if the SVG is loaded (check the <style> or <svg> tags injected by the package).
• Style Overrides: Log the active styles with:

  \Log::info('Active styles:', UntitleduiIcons::make()->getStyles());
  

Extension Points

1. Custom Styles: Extend the package by adding new styles (e.g., UntitleduiIcons::make()->addStyle('custom', 'path/to/style.css')) if the default "Regular" doesn’t meet needs.

2. Icon Alias Extensions: Override the getIconAliases() method in a service provider to map custom aliases to Untitled UI icons:

   UntitleduiIcons::extend(function ($plugin) {
       $plugin->alias('custom-icon', 'untitled-ui-icon-name');
   });
   

3. Dynamic Loading: For large admin panels, defer icon loading by implementing a custom UntitleduiIcons class that conditionally loads styles based on the current route:

   public function getStyles(): array
   {
       return request()->routeIs('admin.resources*') ? ['bold'] : ['regular'];
   }