A Filament plugin for visual image annotation
Tech stack: PHP 8.2+, Laravel, Filament v5, Livewire, Annotorious, Alpine.js
Source: github.com/zielu92/filament-image-labeler
The Problem
Admin panels frequently need image annotation capabilities — tagging regions of interest on photos, marking defects in product images, labeling training data for ML pipelines, or letting content editors highlight areas of an image. Most solutions require leaving the admin panel for a separate tool, or building a custom JavaScript integration from scratch.
The Solution
Filament Image Labeler is an open-source Filament plugin that brings canvas-based image annotation directly into any Filament form. Users draw rectangles and polygons on images, and the package handles persistence through a polymorphic Eloquent relationship — meaning any model in your app can have annotations attached to it with zero schema changes beyond a single migration.
How It Works
The package has two layers:
Frontend – An ImageLabel form field renders the image with an Annotorious overlay. Users draw shapes directly on the canvas. The component emits W3C Web Annotation-compliant geometry data as its Livewire state.
Backend – A polymorphic annotations table stores geometry and optional metadata JSON for each annotation. The HasAnnotations trait provides a syncAnnotations() method that handles create, update, and delete in a single call – similar to Eloquent’s sync() for relationships.
Key Design Decisions
- Polymorphic persistence — One annotations table serves every model in the app. No per-model migrations needed.
- Hash-based color assignment — Each annotation gets a deterministic color derived from its UUID via a djb2 hash. Colors remain stable regardless of annotation order, which avoids confusing color shifts when items are reordered or deleted.
- Metadata flexibility — A nullable JSON metadata column lets each app store whatever domain-specific data it needs (labels, confidence scores, categories) without schema changes.
- W3C Web Annotation format — Geometry is stored using the W3C standard, making it interoperable with other annotation tools and ML pipelines.
Features
- Rectangle and polygon drawing tools
- Colored annotations with customizable palettes
- Works with both public and private (signed URL) file storage
- Pairs naturally with Filament Repeaters for editable metadata per annotation
- Cascade deletes when the parent model is removed
- Filament v5 compatible
Integration Example
Adding annotations to a model takes three steps:
- Add the HasAnnotations trait to your Eloquent model
- Drop an ImageLabel::make(’annotations’) field into your Filament form
- Call $record->syncAnnotations($data) in your page’s afterCreate / afterSave hook
- The plugin stays out of your way — it handles the drawing UI and storage, while your app controls what metadata to attach and how to display it.