# @shelf/image-preview-overlay

> Plain wrapper that renders full image preview on child image tag click

Latest version **1.5.2** (published 2026-10-15) · UNLICENSED license · 0 weekly downloads

## Install

```sh
npm install @shelf/image-preview-overlay
pnpm add @shelf/image-preview-overlay
yarn add @shelf/image-preview-overlay
bun add @shelf/image-preview-overlay
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.5.2 |
| Published | 2026-10-15 |
| First published | 2024-03-01 |
| Weekly downloads | 0 |
| License | UNLICENSED |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 1 |
| Unpacked size | 17.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Shelf |
| Maintainers | el_scrambone, yuliiakovalchuk, gemshelf, hartzler, olesiamuller, vladgolubev, hmelenok, knupman, maaraanas, terret, chapelskyi.slavik, ahavrysh, pihorb, diana.kryskuv, andy.raven, demiansua, yuriil, vadymaslovskyi, ktv18, drews_abuse, rostyslav-horytskyi, whodeen, andriisermiahin, mpushkin, ss1l, oles.zadorozhnyy, maksym.hayovets, domovoj, vladmarchuk, ncqpele, marianna-milovanova, maksym.tarnavskyi, plazowicz, timorohnershelf, pietras, danylo_pantielieiev, ulianak, dymitrkorlotian, dariiakohutiak, vladabramov, paulchiappetta, denys-boichuk, theholiday, liamcooney, yaroslav_korolchuk |
| Keywords | image, preview, fullscreen, react |

## Links

- npm: https://www.npmjs.com/package/@shelf/image-preview-overlay
- Repository: https://github.com/shelfio/libs-frontend
- Homepage: https://github.com/shelfio/libs-frontend#readme
- Issues: https://github.com/shelfio/libs-frontend/issues
- npm.io page: https://npm.io/package/@shelf/image-preview-overlay

## Dependencies (1)

- [@shelf/hotkeys](https://npm.io/package/@shelf/hotkeys.md) ^1.2.4

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.5.2 (latest) — 2026-10-15
- 1.5.1 — 2026-09-11
- 1.4.6 — 2026-09-02
- 1.4.5 — 2026-09-02
- 1.4.4 — 2026-09-02
- 1.4.3 — 2026-08-22
- 1.4.2 — 2026-08-10
- 1.4.1 — 2026-08-07
- 1.4.0 — 2026-07-06
- 1.3.1 — 2026-07-06
- 1.3.0 — 2024-03-05
- 1.2.1 — 2024-03-04
- 1.2.0 — 2024-03-04
- 1.1.0 — 2024-03-01

## README

## Installation

Note: uses styled-components

Install the library using npm:

```shell
$ npm install styled-components
```

```shell
$ npm install @shelf/image-preview-overlay
```

Install the library using yarn:

```shell
$ yarn add styled-components
```

```shell
$ yarn add @shelf/image-preview-overlay
```

## Props

| Prop Name                                           | Type                                          | Description                                                                                                                                                     |
| --------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| getImages                                           | `function (optional)`                         | A function that can be used to modify preview images list. Signature: `(event: ElementMouseEvent) => {src: string; alt?: string}[] \| undefined`                |
| getInitialPreviewImageIndex                         | `function (optional)`                         | A function to customly choose the initial image from the list to be shown when fullview is opened                                                               |
| startPreviewFromTargetImage                         | `boolean (optional)`                          | Default false (always opens first image from the list). If set to true - will try to open the target image (if it is present in the list returned by getImages) |
| triggerProps, portalWrapperProps, imageOverlayProps | `HTMLAttributes<HTMLDivElement> (optional)`   | HTML attributes passed to the corresponding elements                                                                                                            |
| imageProps                                          | `HTMLAttributes<HTMLImageElement> (optional)` | HTML attributes passed to the fullview image element                                                                                                            |

## Usage

### ImagePreviewOverlay

`ImagePreviewOverlay` is a wrapper that renders a full image preview when a child image is clicked.
The preview supports click-to-zoom, zoom controls from 100% to 300%, and scrolling around a zoomed
image. Zoom resets when the user changes images or closes the preview.

```js
import {ImagePreviewOverlay} from '@shelf/image-preview-overlay';

// Simple usage
const Component = () => (
  <ImagePreviewOverlay>
    <span>
      Shelf.io
      <p>
        <img src={'shelf.io'} />
      </p>
    </span>
  </ImagePreviewOverlay>
);

// Custom getImages prop and multiple images
const Component = () => {
  const getImages = _event => [
    {
      src: 'source-1',
      alt: 'source 1 alt',
    },
    {
      src: 'source-2',
    },
  ];

  return (
    <ImagePreviewOverlay getImages={getImages}>
      <img src={'image-snippet-src'} />
    </ImagePreviewOverlay>
  );
};
```

## Publish

```sh
$ git checkout master
$ yarn version
$ yarn publish
$ git push origin master --tags
```

## License

MIT © [Shelf](https://shelf.io)

---
_Source: https://npm.io/package/@shelf/image-preview-overlay · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
