image_hotspot — Flutter Package

What it does

image_hotspot lets a Flutter app define clickable regions on top of a static image — floor plans with tap targets, annotated diagrams, interactive product photos — without reinventing hit-testing for each screen.

The package is on pub.dev with versioned releases, a CHANGELOG, a GitHub Actions publish workflow, and a unit test suite covering the core widget.

Why it exists

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

Decisions & tradeoffs

Hotspots use normalized fractional coordinates relative to the image (0.0–1.0) instead of fixed pixels. The same definition stays aligned across device densities and layout sizes; authors must think in fractions rather than screen pixels.

The package stays focused on hit-testing and region definition — not an authoring editor — so the dependency footprint stays minimal and drop-in use stays simple.

flowchart TD
  UserTouch[User Touch Event] --> Pointer[Global Screen Pointer]
  Pointer --> MatrixTransform[Viewport Scale and Offset]
  MatrixTransform --> RelativeVector[Normalized Coordinate 0.0-1.0]
  RelativeVector --> HitTest{Spatial Hit Test}
  HitTest -->|Inside Zone| Trigger[Dispatch Hotspot Event]
  HitTest -->|Outside Zone| Pass[Pass Event Through]

What it demonstrates

• Flutter package authorship: versioning, CHANGELOG, example app, tests
• Composable API design: consumer owns data and tap handlers; widget owns hit-testing
• CI for package delivery: GitHub Actions publish to pub.dev