astro-hotspot

Astro's built-in image cropping picks from a fixed nine-anchor enum ("center", "top", "right top", "attention", …). For any image where the subject sits between those anchors — a face slightly off to one side, a product in the lower third — there's no way to say "crop around this exact point" when you resize.

astro-hotspot adds a hotspot prop — same idea as CSS object-position / background-position, but applied to the underlying crop — on <Image>, <Picture>, and getImage(). The framing holds at every requested aspect ratio.

Install

pnpm add astro-hotspot

// astro.config.js
import { defineConfig } from "astro/config";
import hotspot from "astro-hotspot";

export default defineConfig({
  integrations: [hotspot()],
});

Use

<Image src={hero} alt="…" width={1200} height={1600} hotspot="70% 34%" />
<Image src={hero} alt="…" width={1200} height={1600} hotspot={{ x: 0.7, y: 0.34 }} />

Two equivalent forms — percent string or {x, y} in [0, 1]. Values outside the range are clamped ("-10% 50%" snaps to the left edge).

When you don't need it

If your subject is roughly centered, Sharp's built-in position="attention" (entropy-based auto-focus) gets it right most of the time and ships with Astro already. Reach for astro-hotspot when auto-focus misframes a particular image and you want explicit control.

License

MIT