ImageViewer
image-viewerOpens images in a full-screen viewer with anchored zoom, panning, navigation, and thumbnails.
Usage
Controlled usage
open / index are all controlled; click the trigger button to set open=true to open full screen Lightbox, support wheel zoom, double-click 1x/2x, ← → Turn page, Esc close.
Open viewer
tsx
const [open, setOpen] = useState(false);
const [index, setIndex] = useState(0);
<>
<button onClick={() => { setIndex(0); setOpen(true); }}>
Open viewer
</button>
<ImageViewer
open={open}
onOpenChange={setOpen}
images={[
{ src: "/a.jpg", alt: "A", caption: "Description A" },
{ src: "/b.jpg", alt: "B", caption: "Description B" },
]}
index={index}
onIndexChange={setIndex}
/>
</>Single picture (no page turning)
images When there is only one image, the left and right page buttons and bottom thumbnail bar are not rendered, only zoom/close is retained.
View large image
tsx
<ImageViewer
open={open}
onOpenChange={setOpen}
images={[{ src: "/poster.jpg", alt: "Poster", caption: "Activity Main Visual" }]}
index={0}
onIndexChange={() => {}}
/>When to use
Use ImageViewer for fullscreen album, work-photo, or attachment inspection. Use [Sparkline] for an inline trend or [LiveProductCard] for commerce content.
Import
ts
import { ImageViewer } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| open* | boolean | — | Controlled visibility. |
| images* | ImageViewerImage[] | — | {src, alt?, caption?} images. |
| index* | number | — | Controlled current image index. |
| className | string | — | Panel class name. |
Events
| Event | Type | Description |
|---|---|---|
| onOpenChange* | (open: boolean) => void | Close request from Escape, overlay, or close control. |
| onIndexChange* | (index: number) => void | Paging request from controls, keyboard, or thumbnails. |
Example
tsx
const [open, setOpen] = useState(false);
const [index, setIndex] = useState(0);
<ImageViewer open={open} onOpenChange={setOpen}
images={[{ src: "/a.jpg", alt: "A", caption: "Description" }, { src: "/b.jpg", alt: "B" }]}
index={index} onIndexChange={setIndex} />Usage notes
- Both open and index are controlled; write callback values to state.
- Scale and offset reset when index or open changes and should not be cached externally.
- Only the current large image renders. Reset index to the intended thumbnail before opening.
- Built-in accessibility labels remain Chinese at runtime:
"\u5173\u95ed\u56fe\u7247\u67e5\u770b\u5668"("Close image viewer"),"\u4e0a\u4e00\u5f20"("Previous image"),"\u4e0b\u4e00\u5f20"("Next image"), and `
Related
Sparkline · LiveProductCard · DiffStat · ScoreRing · Badge · Dot