Download the PHP package asignua/filament-image-meta without Composer

Filament Image Meta

Per-file alt text, a decorative flag, caption, title and a focal point for Filament 5's own FileUpload and SpatieMediaLibraryFileUpload: one wrapper around the upload you already have, no media system to adopt.

Core FileUpload has no per-file metadata at all, and people keep asking for it:

• filamentphp/filament#8455: alt text per uploaded file.
• filamentphp/filament#14652: a focal point on images.

The alternatives are all-or-nothing: Curator solves it if you move your whole media handling into Curator, and the focal-point pickers are a separate field that knows nothing about the upload. This plugin is the small layer in between, with an accessibility and SEO point of view:

• Alt text, per language if you need it. An image without alt makes screen readers read the file name; an image with alt="IMG_0042-final.jpg" is worse than none. The plugin never falls back to the file name.
• "Decorative image" is a decision, not an empty box. A decorative image renders alt="" on purpose; an image nobody described is reported as missing (a badge in the form, an optional data-alt-missing in the HTML, an optional validation error), never silently treated as decorative.

• A focal point (x/y in percent) you set by clicking, dragging or with the arrow keys, rendered as object-position so a crop keeps the face in the frame.

• Screenshots
• Requirements
• Installation
• Usage
• Storage
• Rendering
• Reading the details
• Validation
• Configuration
• Gotchas
• Translations
• AI agents
• Testing

Screenshots

Requirements

• PHP 8.3+
• Laravel 12 or 13
• Filament 5

Optional: filament/spatie-laravel-media-library-plugin and spatie/laravel-medialibrary for SpatieMediaLibraryFileUpload.

Installation

The plugin registers itself (no panel plugin to add). The focal-point picker is a small Alpine component that is only downloaded by a page that opens the modal. Optionally publish the config:

Usage

Wrap the upload:

SpatieMediaLibraryFileUpload works the same way:

Every uploaded image gets a row under the upload: thumbnail, name, the alt text, a status badge (Alt text set, Decorative, Alt text missing, Focal point) and an Edit details button that opens the modal. It works on new, not-yet-saved uploads too.

ImageMetaUpload::make() returns a plain Group that contains the upload and the details panel side by side. Put the result in components([...]); configure the upload (->image(), ->disk(), ->multiple()...) before wrapping it.

• Layout is set on the returned Group, which spans the full row by default: a ->columnSpan() on the upload no longer moves anything once it is wrapped. Use ImageMetaUpload::make(...)->columnSpan(1) instead.
• The panel follows the upload. A ->disabled() upload gets a read-only panel without the Edit details button, and its details are not saved; a ->hidden() upload hides the panel too.

Storage

Plain FileUpload

The details are written to a sibling attribute called {name}_meta (photo → photo_meta), as one JSON object keyed by the stored file path:

A language-less field (locales: []) stores plain strings ("alt": "A red door"). Files that are removed take their details with them on save; a new file stored under the path of a removed one starts with no details.

A save rewrites only what the field manages, for every kept file whether its modal was opened or not: the details it does not collect (a field without caption: keeps the stored caption, title and focal point the same way) and the texts in languages outside its locales (an earlier language list, another site or tool) are kept from the stored entry. Marking an image decorative removes its alt text in every language.

SpatieMediaLibraryFileUpload

Nothing to add to the model. After the upload has saved its files, the details are written to the custom_properties of each media item. The property names are configurable (see Configuration); the defaults are alt, alt_decorative, caption, title and focal_point, so a site that already keeps alt / alt_decorative / caption there needs no data migration. Properties the plugin does not manage (credit, ...) are left alone, and so are the details a field does not collect (a field without title: never touches title), and the texts in languages outside the field's locales (alt.pl survives a field with locales: ['en', 'uk']); a detail that is cleared is removed from the media item.

Rendering

• Text alt → alt="..." (escaped).
• Decorative → alt="", no role, no aria-hidden. (aria-hidden on an <img> is redundant; role="presentation" is redundant with an empty alt. Both are common mistakes.)
• Not described → alt="" as well, and never the file name. With image-meta.mark_missing_alt on, the tag also carries data-alt-missing, so an audit (or [data-alt-missing] { outline: 3px solid red } in staging) finds it.
• Focal point → style="object-position: 31.5% 20%;", appended to a style you pass. Pair it with object-fit: cover (Tailwind object-cover); on its own it does nothing.
• title → the title attribute (not for decorative images). <x-image-meta::figure> adds <figcaption>.

:meta takes an ImageMeta or the stored array. Attributes you pass are merged, never duplicated: your own alt or title replaces the stored one, your style is kept.

Reading the details

There is no fallback between languages unless you set image-meta.fallback_locale: an empty Ukrainian alt on /uk is reported as missing rather than showing the English sentence to a screen reader that expects Ukrainian.

Validation

requireAlt: true adds a rule to the details panel (so it also covers images that are already stored): every image must have alt text in the required locales or be marked decorative; the error names the file and is shown under the file list. fallback_locale does not count: a required language needs its own text. requireAlt also takes a closure, e.g. fn () => auth()->user()->isEditor(). By default only the first locale is required (an English-first site that translates later); list more with requiredLocales: ['en', 'uk'].

Configuration

config/image-meta.php:

Gotchas

• The plain-upload column must be written by your save code. The panel adds photo_meta to the form state. Passing $form->getState() to Model::create() works if the attribute is fillable; a model with $guarded = ['*'] written through a repository or DTO must assign it explicitly, or the value is dropped without an error.
• JSON encoding. The array cast escapes non-ASCII (Д...) in the column. Use a cast that keeps Unicode if you read the database by eye.
• Wrap the finished upload. ImageMetaUpload::make($upload) reads the upload's configuration at render time but returns a Group: methods of the upload (->required(), ->disk()) cannot be called on the result.
• Why a wrapper and not FileUpload::make()->imageMeta()? The details have to live in a state path next to the upload. A component nested inside the upload (belowContent()) gets its state path under the upload's, so it would write into the list of files; and a SpatieMediaLibraryFileUpload is not dehydrated, which makes Filament skip everything nested in it. Siblings avoid both.
• Only images get a row. A non-image file in the same upload is ignored.
• A moved or renamed file loses its details. A plain upload keys the details by stored path; replacing the file creates a new path. (Media-library items are keyed by their uuid and keep theirs.)
• Private disks. The thumbnails use the temporary URLs Filament already generates for the upload.

Translations

English, Ukrainian, German, Spanish, French, Italian, Dutch, Polish, Brazilian Portuguese and Turkish. Publish to override:

AI agents

Laravel Boost guidelines ship in resources/boost/guidelines/core.blade.php.

Testing

The Alpine component is built with npm install && npm run build (esbuild; resources/dist/focal-point.js is committed).

Changelog

See CHANGELOG.

License

The MIT License (MIT). See LICENSE.