Image viewer

When to use #

Use it for

Opening a thumbnail to look closely.

Skip it when

The image is decoration.

Installation #

terminal

pnpm dlx shadcn@latest add https://caliperui.site/r/image-viewer.json

Adds its 4 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above.

example.tsx

import { ImageViewer } from "@/components/ui/image-viewer"

const images = [
  {
    id: "harbour",
    src: "/media/harbour.svg",
    alt: "Quiet harbour",
    caption: "Original Caliper UI illustration · coast study",
  },
  {
    id: "terrace",
    src: "/media/terrace.svg",
    alt: "Terrace arches",
    caption: "Original Caliper UI illustration · architecture study",
  },
  {
    id: "ridge",
    src: "/media/ridge.svg",
    alt: "Northern ridge",
    caption: "Original Caliper UI illustration · landscape study",
  },
];

export function ImageViewerDemo() {
  return (
    <ImageViewer label="Caliper UI studies" images={images} />
  );
}

API reference #

ImageViewer

component

PropTypeDefault

label *string—

images *readonly ViewerImage[]—

classNamestring—

It exposes group and status semantics, with aria-label, aria-hidden and aria-pressed kept in step with state. Changes that matter are announced through a live region.

KeyBehaviour

←Moves to the previous item or value.

→Moves to the next item or value.

↑Moves to the previous item or value.

↓Moves to the next item or value.

Motion #

It declares no animation in its component source. Any transition comes from its stylesheet, which uses the duration tokens that collapse to instant under prefers-reduced-motion.