Zoomable Justified Gallery

Gallery9: Zoomable Justified Gallery

A justified wall with no ragged edge, opening into a viewer where the picture itself is the zoom control: fit to the screen by default, filling it on click.

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/gallery9?email=YOUR_EMAIL&license_key=YOUR_KEY"

Base UI flavor

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

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

Quick start

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

import { Gallery9, gallery9Demo } from "@/components/beste/block/gallery9";

export default function Page() {
  return <Gallery9 {...gallery9Demo} />;
}

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

import { Gallery9 } from "@/components/beste/block/gallery9";

export default function Page() {
  return (
    <Gallery9
      badge={{ label: "Fit or fill" }}
      heading="Open a frame, then push it to full size."
      frames={[
        { src: "/macro/matte.jpg", alt: "Matte surface macro", caption: "Matte surface, macro", meta: "Studio, February" },
        { src: "/macro/edge.jpg", alt: "Brushed edge in low light", caption: "Brushed edge", meta: "Studio, February" },
      ]}
      labels={{
        openLabel: "Open this frame",
        closeLabel: "Close the viewer",
        previousLabel: "Previous frame",
        nextLabel: "Next frame",
        zoomInLabel: "Fill the screen",
        zoomOutLabel: "Fit the screen",
        counterSeparator: "of",
        hint: "Click the picture to switch between fit and fill.",
      }}
    />
  );
}

Props

type Frame = {
  src: string;
  alt: string;
  caption: string;
  meta: string;
};

type Gallery9Labels = {
  openLabel?: string;
  closeLabel?: string;
  previousLabel?: string;
  nextLabel?: string;
  zoomInLabel?: string;
  zoomOutLabel?: string;
  counterSeparator?: string;
  hint?: string;
};

Behavior notes

• The wall is flex flex-wrap with grow basis-72 on every frame, so each row stretches to the full width and the last row has no ragged right edge whatever the count.
• Inside the viewer the picture is itself a button: fit is object-contain with a radius, fill is size-full object-cover with none, and the cursor switches between zoom-in and zoom-out to say which is available.
• The zoom state resets to fit whenever a frame is opened or stepped, so a new picture never arrives already cropped.
• The transition is on the image class rather than a transform, so switching between fit and fill eases instead of jumping.
• The same zoom action is duplicated as a labelled control in the toolbar, so the interaction is reachable by keyboard and its label swaps with the state.
• Escape closes and the left and right arrows step through, wrapping in both directions.
• Setting lightbox={false} disables every frame button and switches the cursor back to default, leaving a plain justified wall.
• Viewer tokens are fixed background shades on a bg-foreground/95 surface, correct for a panel that is dark in both themes.