Loupe Surface StudiesPRO

Gallery21: Loupe Surface Studies

A grid of surface studies whose viewer hands you a loupe: a round window you drag across the work, redrawing whatever sits under it at the magnification you set.

Installation

Swap YOUR_EMAIL and YOUR_KEY for the email and license key on your account. Find your license key on your account page.

Radix flavor

npx shadcn add "https://ui.beste.co/r/gallery21?email=YOUR_EMAIL&license_key=YOUR_KEY"

Base UI flavor

npx shadcn add "https://ui.beste.co/r-base/gallery21?email=YOUR_EMAIL&license_key=YOUR_KEY"

This installs the block to components/beste/block/gallery21.tsx plus the badge7 eyebrow it uses.

Quick start

The installed file exports gallery21Demo alongside the block: the exact props behind the preview above. Spread it to get a working gallery in one line.

import { Gallery21, gallery21Demo } from "@/components/beste/block/gallery21";

export default function Page() {
  return <Gallery21 {...gallery21Demo} />;
}

Then replace the demo with your own props. Written out, a trimmed setup looks like this:

import { Gallery21 } from "@/components/beste/block/gallery21";

export default function Page() {
  return (
    <Gallery21
      badge={{ label: "Surface studies" }}
      heading="Close enough to see the tooth of the paper."
      magnification={2.5}
      studies={[
        {
          src: "/studies/ground.jpg",
          alt: "Matte cotton surface, macro",
          title: "Ground, Enlarged",
          artist: "Idris Kane",
          surface: "Pigment on matte cotton",
        },
        {
          src: "/studies/ply.jpg",
          alt: "Plied wool on a spool",
          title: "Ply (Second State)",
          artist: "Nadia Brühl",
          surface: "Undyed wool, unspun ends",
        },
      ]}
      labels={{
        openLabel: "Take the loupe to this work",
        closeLabel: "Put the loupe down",
        previousLabel: "Previous study",
        nextLabel: "Next study",
        loupeLabel: "Move the loupe",
        hint: "Press and drag on the work to move the loupe.",
        counterSeparator: "of",
      }}
    />
  );
}

Props

type Study = {
  src: string;
  alt: string;
  title: string;
  artist: string;
  surface: string;
};

type Gallery21Labels = {
  openLabel?: string;
  closeLabel?: string;
  previousLabel?: string;
  nextLabel?: string;
  loupeLabel?: string;
  hint?: string;
  counterSeparator?: string;
};

Behavior notes

• The loupe window is a fixed pixel size and the copy inside it is the whole frame scaled by magnification, positioned in pixels from the measured frame, so the point under the glass is genuinely enlarged rather than shrunk to fit the circle.
• The frame is measured into state on open inside a requestAnimationFrame and again on every move, so the magnification is correct before the first drag and stays correct after a resize.
• onDragStart calls preventDefault and both images are draggable={false}, because without that the browser starts dragging the picture and cancels the pointer stream mid-gesture.
• The pointer is captured on press, so a fast drag that leaves the frame keeps moving the loupe until release.
• touch-none is set on the frame, so a touch drag moves the loupe instead of scrolling the page.
• The loupe recentres whenever a study is opened or stepped, so a new work never arrives with the glass parked in a corner.
• The magnification is printed under the picture, so the visitor knows what they are looking at.
• Setting lightbox={false} disables every study button and switches the cursor back to default, leaving a plain grid of surfaces.