Weave Code
Filament Image Annotations Laravel Package
asignua/filament-image-annotations
A Filament plugin for annotating images directly in your admin panel. Add drawing and marking tools to image fields, making it easy to highlight areas, add notes, and manage annotated uploads in Laravel Filament apps.
Non-destructive annotations for images in Filament 5: arrows, shapes, pen, highlighter and text drawn as a separate JSON layer over the picture. Editor field, read-only viewer and an Annotate button on uploads; the original file is never changed.
Frequently asked questions about Filament Image Annotations
- How do I install asignua/filament-image-annotations in Laravel?
- Install it with composer require asignua/filament-image-annotations and then add the editor field, the read-only viewer, or the Annotate action to your Filament image components. The package ships its own Blade views and styles, so rebuild your Vite assets after installing. The release notes mention no migrations, service-provider bindings or config keys, but check the README for any publishable assets in your installed version.
- Does the plugin modify or overwrite the original uploaded image?
- No. Annotations are drawn as a separate JSON layer rendered over the picture, and the original file is never changed. That means you can edit, hide or delete marks at any time without re-uploading or regenerating the asset. The trade-off is that you are responsible for persisting and reloading the JSON layer alongside your media record.
- Which Filament version does this package support?
- The package targets Filament 5, so it fits Laravel applications already running a Filament 5 panel. Support for earlier Filament majors is not indicated, and the editor relies on Filament form-field and action APIs that shifted across major versions. Check the composer.json constraints before installing into an older panel.
- How are the annotations stored, and where should I persist them?
- The package owns presentation and delegates persistence to the host application, so you typically store the JSON layer in a JSON column on your media or attachment model. The release notes do not document the coordinate space used inside that JSON, whether normalized 0-1, pixels or percentage strings, and that is the key detail to confirm before reusing marks across different surfaces. There is also no mention of server-side validation or normalization, so bounds checking of client-submitted positions remains your responsibility.
- What is bare overlay mode and when should I use it?
- Bare overlay mode decouples the mark layer from image ownership, letting you place pins and drawings over an image rendered by someone else, such as chat thumbnails, third-party galleries or CMS-rendered media. You mount the component without binding its image x-ref, set data-aspect to the true width/height ratio, and optionally set data-fit to cover and data-interactive to false. It is the cleanest way to reuse annotations across surfaces without forking the package.
- Can I use the read-only viewer outside a Filament panel?
- Yes. The viewer is a Blade component driven by data attributes, so it can be dropped into any Blade or Livewire view, including modals and thumbnails, as long as Alpine is available. Watch for Alpine re-initialization when Livewire morphs the DOM, since the component must mount idempotently. Also verify it against your Tailwind preflight, because the framed stage introduces border and shadow styling that resets can affect.
- Is data-aspect required, and what happens if the ratio is wrong?
- data-aspect is what makes the overlay math deterministic, because it lets the component compute mark positions without waiting for the image load event. In practice you should always set it to the true width/height ratio of the rendered image and treat a stale or wrong value as a silent bug that misplaces every mark. Confirm in the README whether bare overlay mode treats it as mandatory and what fallback applies before the image finishes loading.
- Does data-fit cover mode match browser object-fit behavior?
- Setting data-fit to cover implies the package reimplements object-fit cover crop math in JavaScript, so marks line up with the visible crop. Verify that it also honors the equivalent of object-position, otherwise non-centered crops will diverge from what users actually see. Test at non-1:1 aspect ratios, where rounding differences show up most often.
- Are annotations accessible when the viewer is read-only?
- Setting data-interactive to false is the right primitive for read-only thumbnails, but confirm it removes marks from the tab order and the accessibility tree rather than merely suppressing pointer events. The release notes describe the attribute but not its accessibility semantics. If screen-reader users need to perceive the annotations, pair the viewer with a text summary rendered from the same JSON.
- Is upgrading to 1.2.0 safe, and do I need the Pro add-on?
- Version 1.2.0 is additive: new data attributes plus cosmetic CSS on the editor chrome, with no migrations, routes or config changes mentioned, so a ^1.2 constraint bump is semver-consistent. Adopt bare overlay mode deliberately rather than as a side effect of the update, and expect editor stage and toolbar visual-regression snapshots to change. The open-source package is the integration contract consumed by the commercial Pro add-on, so pin both and test them together rather than bumping each independently.
Weaver
How can I help you explore Laravel packages today?