Filterable Album Grid

Gallery3: Filterable Album Grid

Photographs sorted into albums, switched with pill filters and a summary line that carries the frame count. The viewer opens on the page's own surface, with the picture on one side and a detail column holding the caption, the controls and the rest of the album.

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

Base UI flavor

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

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

Quick start

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

import { Gallery3, gallery3Demo } from "@/components/beste/block/gallery3";

export default function Page() {
  return <Gallery3 {...gallery3Demo} />;
}

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

import { Gallery3 } from "@/components/beste/block/gallery3";

export default function Page() {
  return (
    <Gallery3
      badge={{ label: "Albums" }}
      heading="Three years of work, sorted by where it happened."
      albums={[
        {
          label: "In the studio",
          summary: "Desks, walls and the state of the floor between deadlines.",
          images: [
            { src: "/albums/studio-1.jpg", alt: "Specimens on a desk", caption: "Specimens, mid-selection" },
            { src: "/albums/studio-2.jpg", alt: "Team at a shared table", caption: "Thursday review" },
          ],
        },
        {
          label: "On site",
          summary: "Installations, mostly photographed before anyone arrived.",
          images: [
            { src: "/albums/site-1.jpg", alt: "Signage on a lobby wall", caption: "Wayfinding, level two" },
          ],
        },
      ]}
      labels={{
        countSuffix: "frames",
        openLabel: "Open this frame",
        closeLabel: "Close the viewer",
        previousLabel: "Previous frame",
        nextLabel: "Next frame",
        counterSeparator: "of",
        detailTitle: "Also in this album",
      }}
    />
  );
}

Props

type Album = {
  label: string;
  summary: string;
  images: AlbumImage[];
};

type AlbumImage = {
  src: string;
  alt: string;
  caption: string;
};

type Gallery3Labels = {
  countSuffix?: string;
  openLabel?: string;
  closeLabel?: string;
  previousLabel?: string;
  nextLabel?: string;
  counterSeparator?: string;
  detailTitle?: string;
};

Behavior notes

• Switching album also clears the open frame, so the viewer can never be left showing a picture from a set you are no longer looking at.
• The viewer is light rather than dark: it fills the screen on bg-background, with the picture on the page's own surface and a bordered detail column beside it, so nothing is layered on top of the photograph.
• That column carries the caption, the album summary, the step controls and a thumbnail grid of the whole album, so you can move sideways through the set without closing anything.
• Thumbnails fade to opacity-40 when they are not the open frame, which marks the position without adding a border or a colour.
• Setting lightbox={false} disables every frame button and switches the cursor back to default, leaving a plain filterable grid.
• Escape closes and the left and right arrows step through, with the index wrapping inside the current album only.
• The frame count is rendered as a number plus a countSuffix you supply, so it stays translatable without string concatenation in the block.
• Below md the detail column moves under the picture and gains a top border instead of a left one, so the viewer stays usable on a phone.