image_hotspot — Flutter Package

[!VERIFY] pub.dev metrics (downloads, likes, current published status) need to be re-confirmed before this is emphasized in outreach contexts — package registries change over time and this entry should not be treated as live data.

What it does

image_hotspot lets a Flutter app define clickable/tappable regions on top of a static image — useful for floor plans with clickable rooms or tables, annotated diagrams, or interactive product photos — without building custom hit-testing logic for each use case.

Why it exists

This came out of a related project, Floor Plan Builder, which needed interactive table/seat regions on a floor plan image. Rather than keep that hit-testing logic embedded in one app, it was extracted into a standalone, reusable package.

Key Decisions & Tradeoffs

The core API decision was defining hotspots as normalized (fractional) coordinates relative to the image rather than fixed pixel positions. That makes a hotspot definition resolution-independent — the same floor plan image can render at any size or device density and the clickable regions stay correctly aligned — at the cost of needing consumers to think in fractions of image width/height rather than concrete pixels when authoring hotspot data.

Keeping the package focused on hit-testing and region definition, rather than also providing image-editing or hotspot-authoring tooling, kept its surface area small and its dependency footprint minimal — appropriate for a package meant to be dropped into other apps’ widget trees rather than used as a standalone tool.

Lessons Learned

Extracting a focused capability (tap regions on an image) into its own package — rather than leaving it embedded in the app that first needed it — made it reusable for the floor-plan use case and any future image-annotation needs, at the cost of needing a clean, app-agnostic API surface from the start.

The fractional-coordinate decision in particular generalized further than expected: any future image-annotation case that needs to render the same base image at different sizes — a thumbnail vs. a full-screen view, for example — gets resolution independence for free, without needing a second code path that recalculates hotspot positions per rendered size.

It’s also a reminder that small, single-purpose packages tend to outlive the app that first justified building them, simply because the cost of reusing one is far lower than the cost of re-implementing the same hit-testing logic from scratch every time a similar need shows up in an unrelated project.