Data Display

Image Zoom

Inline hover/press zoom that magnifies product imagery and pans with the cursor.

Import

tsx

import { ImageZoom } from "@cronus-ui/ui";

bash

npx cronus-ui add image-zoom

Examples

Hover to zoom

Product-style inline zoom: a fine pointer magnifies on hover and the pan follows the cursor via transform-origin tracking; touch taps and Enter/Space toggle a sticky zoom instead. The zoom indicator fades away while zoomed.

tsx

<ImageZoom
  src="https://picsum.photos/seed/cronus-product/900/600"
  alt="Studio product photo"
  className="max-w-md"
/>

Zoom scale

`zoom` sets the magnification applied while zoomed (values below 1 clamp to 1). Defaults to 2.

zoom 2 (default)

zoom 4

tsx

<div className="grid w-full max-w-2xl gap-4 sm:grid-cols-2">
  <div className="flex flex-col items-center gap-2">
    <ImageZoom src="https://picsum.photos/seed/cronus-loft/700/500" alt="" />
    <span className="text-sm text-fg-secondary">zoom 2 (default)</span>
  </div>
  <div className="flex flex-col items-center gap-2">
    <ImageZoom
      src="https://picsum.photos/seed/cronus-loft/700/500"
      alt=""
      zoom={4}
      labels={{ zoom: "Zoom image (4×)" }}
    />
    <span className="text-sm text-fg-secondary">zoom 4</span>
  </div>
</div>

Custom image & zoom state

Wrap your own `<img>` instead of passing `src`, rename the accessible toggle via `labels`, and observe the state with `onZoomChange`.

Hover, tap or press Enter to zoom

tsx

function ImageZoomStateDemo() {
  const [zoomed, setZoomed] = useState(false);
  return (
    <div className="flex w-full max-w-md flex-col items-center gap-3">
      <ImageZoom zoom={3} onZoomChange={setZoomed} labels={{ zoom: "Zoom fabric detail" }}>
        <img src="https://picsum.photos/seed/cronus-fabric/1200/675" alt="" />
      </ImageZoom>
      <Badge variant={zoomed ? "primary" : "secondary"}>
        {zoomed ? "Zoomed 3×" : "Hover, tap or press Enter to zoom"}
      </Badge>
    </div>
  );
}

API Reference

Generated from the component's exported types.

ImageZoomProps

Extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof imageZoomVariants>

Prop	Type	Default	Description
`src`	`string`	—	Image URL for the built-in `<img>`. Ignored when `children` is passed.
`alt`	`string`	`""`	Describes the image for assistive tech. The root is a button whose `aria-label` overrides the inner image's alt, so the description is composed into the toggle's accessible name (`"{labels.zoom}: {alt}"`) in addition to serving as the built-in `<img>` alt.
`zoom`	`number`	`2`	Magnification applied while zoomed. Values below `1` clamp to `1`.
`disabled`	`boolean`	`false`	Disables all zoom interaction.
`showIndicator`	`boolean`	`true`	Renders the zoom-in indicator overlay, which fades out while zoomed.
`labels`	`Partial<ImageZoomLabels>`	—	Assistive strings, merged over the English defaults.
`zoomed`	`boolean`	—	Controlled zoom state. Pair with `onZoomChange`.
`defaultZoomed`	`boolean`	`false`	Initial zoom state for uncontrolled usage.
`onZoomChange`	`(zoomed: boolean) => void`	—	Called with the next state whenever zoom toggles on or off.
`children`	`ReactNode`	—	Custom image markup to zoom instead of the built-in `src` image.