Filament Character Counter Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require schmeits/filament-character-counter:"^5.0"
   

   Publish the config (optional, for customization):

   php artisan vendor:publish --provider="Schmeits\FilamentCharacterCounter\FilamentCharacterCounterServiceProvider"
   

2. First Use Case: Replace a standard TextField, Textarea, or RichEditor in a Filament form with the character-counter variant:

   use Schmeits\FilamentCharacterCounter\Fields\CharacterCounterTextField;
   
   CharacterCounterTextField::make('bio')
       ->maxLength(200)
       ->columnSpanFull(),
   

3. Where to Look First:

   • Package README for version compatibility.
   • config/filament-character-counter.php for default styling/config.
   • Filament Docs for field customization patterns.

Implementation Patterns

Core Workflows

1. Basic Integration: Replace any text-based field with its CharacterCounter* counterpart:

   // Before
   Textarea::make('description')->rows(5),
   
   // After
   CharacterCounterTextarea::make('description')
       ->maxLength(500)
       ->helperText('Max 500 characters.'),
   

2. Dynamic Limits: Use closures for runtime limits (e.g., based on user roles):

   CharacterCounterTextField::make('tagline')
       ->maxLength(fn () => auth()->user()->isAdmin() ? 100 : 50),
   

3. RichEditor Integration:

   use Schmeits\FilamentCharacterCounter\Fields\CharacterCounterRichEditor;
   
   CharacterCounterRichEditor::make('content')
       ->maxLength(1000)
       ->toolbarButtons([
           'bold', 'italic', 'link',
       ]),
   

4. Form-Level Validation: Combine with Filament’s built-in validation:

   CharacterCounterTextField::make('title')
       ->required()
       ->maxLength(150)
       ->rules(['unique:posts']),
   

Advanced Patterns

1. Conditional Rendering: Toggle the counter based on field state:

   CharacterCounterTextarea::make('notes')
       ->maxLength(300)
       ->showCharacterCounter(fn ($state) => strlen($state) > 0),
   

2. Custom Styling: Override default CSS via the config:

   // config/filament-character-counter.php
   'character_counter' => [
       'color' => 'text-red-500',
       'font_size' => 'text-sm',
   ],
   

3. Localization: Translate counter labels:

   CharacterCounterTextField::make('slogan')
       ->maxLength(80)
       ->characterCounterLabel(fn () => __('filament-character-counter::counter.label')),
   

4. Multi-Field Sync: Sync counters across related fields (e.g., title + excerpt):

   // In a custom field widget or form component
   $this->fields([
       CharacterCounterTextField::make('title')->maxLength(100),
       CharacterCounterTextField::make('excerpt')->maxLength(200),
   ]);
   

Gotchas and Tips

Pitfalls

1. Version Mismatches:

   • Issue: Using ^5.0 with Filament v3.x will fail silently.
   • Fix: Pin to ^1.0 for Filament v3.2 or ^5.0 for v4/v5.
   • Debug: Check composer.json for filament/support version.

2. RichEditor Quirks:

   • Issue: Counter may not reflect real-time changes in the WYSIWYG editor.
   • Fix: Use live prop or debounce updates:

     CharacterCounterRichEditor::make('content')
         ->live()
         ->debounce(500),
     

3. CSS Conflicts:

   • Issue: Counter styling clashes with Filament’s dark mode or custom themes.
   • Fix: Increase specificity in your CSS or override via config:

     .filament-character-counter__counter {
         @apply text-primary-500 !important;
     }
     

4. Max Length Validation:

   • Issue: Client-side counter doesn’t enforce server-side maxLength.
   • Fix: Always include ->maxLength() and Laravel validation rules:

     ->rules(['max:200'])
     ->maxLength(200),
     

Debugging Tips

1. Inspect Rendered HTML: Use browser dev tools to verify the counter element exists:

   <div class="filament-character-counter__counter">120/200</div>
   

   If missing, check for JavaScript errors in the console.

2. Log Field State: Debug dynamic maxLength with:

   ->maxLength(fn () => log('Max length: ' . auth()->user()->role, 'debug'))
   

3. Disable Counter Temporarily: For testing, use:

   ->showCharacterCounter(false),
   

Extension Points

1. Custom Counter Logic: Extend the counter behavior by publishing and modifying the JS:

   php artisan vendor:publish --tag=filament-character-counter-assets
   

   Then edit resources/js/filament-character-counter.js.

2. Add Icons/Tooltips: Use Filament’s icon system:

   ->characterCounterIcon('heroicon-o-information-circle')
   ->characterCounterTooltip(__('Tip: Keep it under 150 chars!')),
   

3. Server-Side Processing: Hook into saving to log character counts:

   use Filament\Notifications\Notification;
   
   $record->save();
   Notification::make()
       ->title('Character count')
       ->body("Title: {$record->title->length()}/100")
       ->send();
   

4. Testing: Use Filament’s testing helpers:

   $this->fillForm([
       'bio' => str_repeat('a', 301), // Exceed max
   ]);
   $this->assertHasErrors(['bio' => 'The bio may not be greater than 300 characters.']);