Pan & Zoom

• Requirements
• Installation
  • Register the Plugin
  • Optional: Publish Assets
• Usage
  • Filament Version Compatibility
    • Filament 3.0+ (Legacy)
    • Filament 4.0+ (Current)
  • Configurable Double-Click Zoom
  • In Blade Views
  • Component Selection Guide
  • Key Differences: Filament 3.0+ vs 4.0+
  • Usage Examples
    • Filament 3.0+ Examples
    • Filament 4.0+ Examples
• Component Properties
• Quick Tips
• Features
  • Zoom Controls
  • Pan Controls
  • Reset View
  • Visual Feedback
• Styling
• Troubleshooting
  • Common Issues
  • Version-Specific Issues
    • Filament 3.0+
    • Filament 4.0+
  • Quick Reference
• Browser Support
• Testing
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

An interactive image zoom and pan component for Filament PHP. This package provides a beautiful, responsive image viewer with smooth zoom and pan functionality, perfect for viewing receipts, documents, or any images that require detailed inspection.

Features:

• 🔍 Mouse wheel zooming
• 🖱️ Click and drag panning
• 🖱️ Double-click zoom to position (configurable level)
• 📱 Touch support for mobile devices
• ⚡ Smooth transitions and animations
• 🎯 Zoom in/out buttons
• 🔄 Reset view functionality
• 📊 Real-time zoom percentage display
• 🎨 Modern, clean UI design

#Requirements

• PHP 8.3+
• Laravel 10.0+
• Filament 3.3+ or 4.0+

#Installation

You can install the package via composer:

composer require solution-forest/filament-panzoom

#Register the Plugin

Add the plugin to your Filament Panel Provider (e.g., app/Providers/Filament/AdminPanelProvider.php):

use SolutionForest\FilamentPanzoom\FilamentPanzoomPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->default()
        ->id('admin')
        ->path('admin')
        // ... other configuration
        ->plugins([
            FilamentPanzoomPlugin::make(),
            // ... other plugins
        ]);
}

#Optional: Publish Assets

Optionally, you can publish the views for customization:

php artisan vendor:publish --tag="filament-panzoom-views"

You can also publish the config file:

php artisan vendor:publish --tag="filament-panzoom-config"

#Usage

#Filament Version Compatibility

This package supports both Filament 3.0+ and Filament 4.0+ with automatic compatibility detection.

#Filament 3.0+ (Legacy)

// Forms, Actions & Tables
use SolutionForest\FilamentPanzoom\Components\PanZoom;

public static function form(Form $form): Form
{
    return $form->schema([
        PanZoom::make('image_preview')
            ->imageUrl(fn ($record) => $record?->image_url)
            ->label('Image Preview')
            ->columnSpanFull(),
    ]);
}

// Infolists
use SolutionForest\FilamentPanzoom\Infolists\Components\PanZoomEntry;

public function infolist(Infolist $infolist): Infolist
{
    return $infolist->schema([
        PanZoomEntry::make('image_preview')
            ->imageUrl(fn ($record) => $record?->image_url)
            ->label('Image Preview'),
    ]);
}

#Filament 4.0+ (Current)

// Forms - Uses Schemas
use SolutionForest\FilamentPanzoom\Components\PanZoom;

public static function configure(Schema $schema): Schema
{
    return $schema->components([
        PanZoom::make('image_preview')
            ->imageUrl(fn ($record) => $record?->image_url),
        // Note: label() and columnSpanFull() methods not available in 4.0+
    ]);
}

// Infolists - Uses Schemas
use SolutionForest\FilamentPanzoom\Infolists\Components\PanZoomEntry;

public static function configure(Schema $schema): Schema
{
    return $schema->components([
        PanZoomEntry::make('image_preview')
            ->imageUrl(fn ($record) => $record?->image_url),
    ]);
}

#Configurable Double-Click Zoom

You can customize the double-click zoom level for each component. Double-clicking again will return the image to the original fit-to-container view:

// Filament 3.0+ Forms
PanZoom::make('image_preview')
    ->imageUrl(fn ($record) => $record?->image_url)
    ->doubleClickZoomLevel(2.5)  // Zoom to 2.5x instead of default 3x
    ->label('Image Preview');

// Filament 4.0+ Forms
PanZoom::make('image_preview')
    ->imageUrl(fn ($record) => $record?->image_url)
    ->doubleClickZoomLevel(4.0)  // Zoom to 4x for more detail
    ->columnSpanFull();

// Infolists (both 3.0+ and 4.0+)
PanZoomEntry::make('image_preview')
    ->imageUrl(fn ($record) => $record?->image_url)
    ->doubleClickZoomLevel(2.0)  // Zoom to 2x
    ->imageId(fn ($record) => 'image-' . $record->id);

Available Zoom Levels:

• Range: 0.5x to 5.0x
• Default: 3.0x (good balance for detail viewing)
• Common values:
  • 2.0 - Moderate zoom
  • 2.5 - Balanced zoom
  • 3.0 - Default (detailed view)
  • 4.0 - High zoom
  • 5.0 - Maximum zoom

#In Blade Views

You can use the component directly in any Blade view (works in both 3.0+ and 4.0+):

@include('filament-panzoom::filament-panzoom', [
    'imageUrl' => 'https://example.com/image.jpg',
    'imageId' => 'unique-image-id',
    'doubleClickZoomLevel' => 2.5  // Custom zoom level (double-click again to return to fit)
])

#Component Selection Guide

⚠️ Important: Choose the correct component for your context!

Why two components? Filament has separate component hierarchies for Forms and Infolists. Using the wrong one will cause a TypeError.

#Key Differences: Filament 3.0+ vs 4.0+

#Usage Examples

#Filament 3.0+ Examples

In Forms:

public static function form(Form $form): Form
{
    return $form->schema([
        PanZoom::make('image_preview')
            ->imageUrl(fn ($record) => $record?->image_url)
            ->label('Image Preview')
            ->columnSpanFull(),
    ]);
}

In Infolists:

use SolutionForest\FilamentPanzoom\Infolists\Components\PanZoomEntry;

public function infolist(Infolist $infolist): Infolist
{
    return $infolist->schema([
        PanZoomEntry::make('receipt_image')
            ->imageUrl(fn ($record) => asset('storage/' . $record->image_path))
            ->label('Receipt Image')
            ->imageId(fn ($record) => 'receipt-' . $record->id),
    ]);
}

In Table Actions:

public static function table(Table $table): Table
{
    return $table->actions([
        Action::make('viewImage')
            ->form([
                PanZoom::make('image_viewer')
                    ->imageUrl(fn ($record) => $record->image_url)
                    ->label('Image Viewer'),
            ])
    ]);
}

In Custom Pages:

protected function getFormSchema(): array
{
    return [
        PanZoom::make('document_viewer')
            ->imageUrl($this->imageUrl)
            ->label('Document Viewer')
            ->columnSpanFull(),
    ];
}

#Filament 4.0+ Examples

In Forms (Schemas):

public static function configure(Schema $schema): Schema
{
    return $schema->components([
        PanZoom::make('image_preview')
            ->imageUrl(fn ($record) => $record?->image_url),
        // Note: label() and columnSpanFull() methods not available in 4.0+
    ]);
}

In Infolists (Schemas):

use SolutionForest\FilamentPanzoom\Infolists\Components\PanZoomEntry;

public static function configure(Schema $schema): Schema
{
    return $schema->components([
        PanZoomEntry::make('receipt_image')
            ->imageUrl(fn ($record) => asset('storage/' . $record->image_path))
            ->imageId(fn ($record) => 'receipt-' . $record->id),
    ]);
}

In Table Actions:

public static function table(Table $table): Table
{
    return $table->actions([
        Action::make('viewImage')
            ->form([
                PanZoom::make('image_viewer')
                    ->imageUrl(fn ($record) => $record->image_url),
            ])
    ]);
}

In Custom Pages:

protected function getFormSchema(): array
{
    return [
        PanZoom::make('document_viewer')
            ->imageUrl($this->imageUrl),
        // Note: columnSpanFull() method not available in 4.0+
    ];
}

#Component Properties

The component accepts the following properties:

#Quick Tips

💡 Pro Tip: Double-click anywhere on the image to zoom to that exact position (configurable, default 3x). Double-click again to return to fit.

#Features

#Zoom Controls

• Mouse Wheel: Scroll to zoom in/out
• Double-Click: Double-click to zoom to exact position (configurable level, default: 3x). Double-click again to return to fit.
• Zoom Buttons: Click the + and - buttons in the control panel
• Zoom Range: 0.5x to 5x magnification

#Pan Controls

• Mouse Drag: Click and drag to pan around the image
• Touch Support: Touch and drag on mobile devices

#Reset View

• Reset Button: Click the reset button to return to the original view
• Auto-fit: Images are automatically fitted to the container on load

#Visual Feedback

• Zoom Percentage: Real-time zoom level display
• Cursor States: Visual feedback for grabbable/grabbing states
• Smooth Transitions: Animated zoom and pan movements

#Styling

The component uses Tailwind CSS classes and is designed to work seamlessly with Filament's design system. The component is fully responsive and includes:

• Modern, clean interface
• Smooth hover effects
• Mobile-friendly touch controls
• Consistent with Filament's design patterns

#Troubleshooting

#Common Issues

TypeError: Argument #1 ($component) must be of type Filament\Infolists\Components\Component

• ❌ You're using PanZoom in an Infolist
• ✅ Use PanZoomEntry for Infolists instead

TypeError: Argument #1 ($component) must be of type Filament\Forms\Components\Component

• ❌ You're using PanZoomEntry in a Form/Action
• ✅ Use PanZoom for Forms/Actions instead

Fatal Error: Class was composed with trait conflicts

• ✅ Fixed in v1.2.1+ - update your package

Method not found: label() or columnSpanFull() in Filament 4.0+

• ❌ These methods aren't available in Filament 4.0+ Schemas
• ✅ Remove these method calls or use Filament 3.0+ syntax

Undefined type 'Filament\Schemas\Components\Component'

• ❌ Linter error in Filament 3.0+ environment
• ✅ This is expected - the package uses runtime detection for compatibility

#Version-Specific Issues

#Filament 3.0+

• ✅ All methods available (label(), columnSpanFull(), etc.)
• ✅ Traditional Forms/Infolists structure

#Filament 4.0+

• ⚠️ Limited methods available (Schemas-based)
• ⚠️ Different structure (configure(Schema $schema))
• ✅ Automatic compatibility detection

#Quick Reference

#Browser Support

• Chrome 70+
• Firefox 65+
• Safari 12+
• Edge 79+

#Testing

composer test

#Changelog

Please see CHANGELOG for more information on what has changed recently.

#Contributing

Please see CONTRIBUTING for details.

#Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

#Credits

• SolutionForest Team
• All Contributors

#License

The MIT License (MIT). Please see License File for more information.