imsyuan/filament-image-caption-upload

Filament v3 FileUpload component with per-image caption support

1.0.0 2026-06-10 07:17 UTC

Requires

• php: ^8.1
• filament/forms: ^3.0

Requires (Dev)

• orchestra/testbench: ^8.0
• pestphp/pest: ^2.0
• pestphp/pest-plugin-laravel: ^2.0

MIT

• imsyuan

• image
• laravel
• file-upload
• caption
• filament
• filamentphp

README

A Filament v3 form component that extends FileUpload to attach a per-image caption to each uploaded file.

Database Format

Each field stores an array of {image, caption} pairs:

[
  { "image": "photos/abc.jpg", "caption": "Living room view" },
  { "image": "photos/def.jpg", "caption": "Kitchen detail" }
]

Requirements

• PHP 8.1+
• Laravel 10+
• Filament 3.x

Installation

composer require imsyuan/filament-image-caption-upload

Usage

use Imsyuan\ImageCaptionUpload\Forms\Components\ImageCaptionUpload;

ImageCaptionUpload::make('photos')
    ->multiple()
    ->image()
    ->captionPlaceholder('Enter a caption…')
    ->reorderable()
    ->appendFiles(),

Cast the model attribute as an array:

// app/Models/Post.php
protected $casts = [
    'photos' => 'array',
];

Options

captionPlaceholder(string|Closure $placeholder)

Sets the placeholder text shown inside each caption input. Defaults to 'Caption...'.

All FileUpload options

ImageCaptionUpload extends Filament's built-in FileUpload, so all existing options work as-is: ->image(), ->multiple(), ->maxFiles(), ->reorderable(), ->panelLayout(), ->disk(), ->directory(), etc.

How it works

1. Hydration — [{image, caption}] is split: paths go to Filament's normal UUID-keyed state; captions are stored in a sibling Livewire key (_icap_<fieldname>).
2. Alpine — A MutationObserver watches for FilePond item additions and injects caption <input> elements beneath each file panel. Captions are entangled back to Livewire state.
3. UUID cache — FilePond internal IDs are mapped to Filament UUIDs so captions survive reorders and upload race conditions.
4. Dehydration — {uuid: path} and {uuid: caption} are zipped back into [{image, caption}] before saving.

License

MIT — see LICENSE.