Filament Image Annotations Laravel Package

Getting Started

This release keeps the entry point the same: install the package, publish its assets/config, and drop the viewer or editor component into a Blade view. The v1.2.0 additions are opt-in data attributes, so existing usage does not need to change.

1. Require the package and publish assets (php artisan vendor:publish for the package tag; check the README for the exact tag/provider registration for your Laravel version).
2. Render the viewer against an image you control, then persist the marks your app cares about. The simplest first use case is annotating a screenshot or product photo with pins and rendering it read-only elsewhere.
3. If you are building an authoring flow, start with the editor component, save the returned mark payload, and render the same payload through the viewer.

The first thing to look at in this release is the new overlay mode: the viewer can now draw marks over a picture rendered by someone else, with no x-ref="image" element. That is the feature to evaluate first if you render thumbnails or third-party images.

Implementation Patterns

Standard viewer with your own image. Keep the image inside the component so the viewer owns the coordinate space. Marks and image share one box, so resize behaviour is handled for you.

Bare overlay over a foreign picture. Omit x-ref="image" entirely and let the host element supply the visual. Size the mark layer with the new attributes:

<div class="relative">
    <img src="{{ $thumbnailUrl }}" class="w-full h-40 object-cover" alt="">

    <x-your-package-viewer
        data-aspect="0.75"
        data-fit="cover"
        data-interactive="false"
        :marks="$marks"
    />
</div>

• data-aspect is height / width, so a 4:3 image is 0.75 and a 16:9 image is 1.777….
• data-fit="cover" makes the marks crop the same way object-fit: cover crops the picture. Without it, marks are positioned in the uncropped space and drift.
• data-interactive="false" stops pins from swallowing clicks. Use it on thumbnails and cards that link to a detail page.

Thumbnail-to-detail workflow. Render data-interactive="false" overlays in list views (chat threads, galleries, search results), and the full interactive viewer or editor on the detail page. The same stored mark payload should drive both; only the presentation attributes differ. This is exactly the Pro add-on pattern described in the release notes, so it is a supported shape rather than a workaround.

Editor authoring flow. The editor now frames the toolbar and puts the image on a tinted, shadowed stage. That is presentation only — it fixes contrast against light modals and works in both light and dark panels, but it does not change the saved payload. Keep saving marks the same way you did before the upgrade.

Server-side persistence. Treat the mark payload as opaque JSON keyed to the model that owns the image, and version it if you expect the coordinate schema to change. Store the aspect ratio alongside the marks where the image can be replaced, so overlays on cached thumbnails stay aligned.

Gotchas and Tips

• data-aspect is inverted from the CSS convention. It is height divided by width, not the 16 / 9 order you would write in aspect-ratio. Getting this backwards produces marks that look subtly wrong rather than obviously broken, which makes it easy to ship.
• data-fit="cover" is not the same as setting object-cover on your <img>. The attribute tells the mark layer how to crop. Setting only the CSS class on the image leaves the marks in the uncropped coordinate space. Set both, and keep them consistent if you ever change one.
• Do not add x-ref="image" in overlay mode. The release notes call this out explicitly: the bare-overlay path assumes no internal image element. Adding a ref puts the viewer back into owned-image mode and the sizing attributes will not do what you expect.
• data-interactive="false" is about click capture, not rendering. The pins still draw; they just stop intercepting pointer events. If a parent anchor still is not clickable, check for an absolutely positioned wrapper above the link in your own markup before blaming the package.
• Stable dimensions before initialisation. Overlay marks are positioned against the rendered box. If the host image has no intrinsic size or loads after Alpine initialises, marks land in the wrong place until the next resize. Give the container an explicit size or aspect ratio, and make sure the mark layer re-measures after the image loads.
• Alpine timing. The x-ref usage confirms an Alpine-driven component. In Livewire or Turbo-style partial updates, re-render the component rather than mutating the DOM around it, or marks will be stale. wire:ignore on the wrapper is the usual fix when the package manages its own DOM.
• Editor chrome is cosmetic. The framed toolbar and tinted stage in v1.2.0 fix a real contrast problem with light screenshots in light modals, but nothing about saving or coordinates changed. Do not chase a regression there when a mark looks off — check aspect and fit first.
• Pro add-on version alignment. The overlay attributes were added to support the Pro add-on's thumbnail use case. If you are running Pro, upgrade both packages together; a mismatched pair is the most likely source of odd cropping behaviour in chat-thumbnail overlays.
• Debugging checklist for misplaced marks: confirm data-aspect is height/width, confirm data-fit matches the image's CSS object-fit, confirm no x-ref="image" in overlay mode, confirm the container has a resolved size at init, then check for custom CSS overriding the mark layer's positioning.
• Asset caching. New data attributes only work if the new JS is actually served. Clear view/asset caches after upgrading, and check your asset pipeline's versioning before concluding the feature is broken.