Staaarter

Filterable Album Grid

An album gallery with pill filter buttons above a grid; picking one swaps which items are visible below by matching each item's album field. Any tile opens a light, full-screen viewer: the picture sits on the page surface on one side while a side column carries the caption, an album summary, prev/next controls, and a numbered thumbnail index list for jumping straight to any photo in the current filter.

By Staaarter Team
Gallery
Docs
Live preview

Docs

Installation

A real shadcn registry command, not a copy-paste stand-in: it fetches this block plus its media-slot dependencies and any missing npm packages, and installs them straight into your project.

npx shadcn add https://staaarter.com/r/filterable-album-grid.json

Prefer not to use the CLI? Copy the source from the Code toggle above into src/components/blocks/gallery/gallery22.tsx instead.

Usage

The file also exports gallery22Demo, the exact props behind the preview above. Spread it to get a working section in one line, then replace it with your own data.

import { Gallery22, gallery22Demo } from "@/components/blocks/gallery/gallery22";

export default function Page() {
  return <Gallery22 {...gallery22Demo} />;
}

Props

PropTypeDefaultDescription
headingstring"Albums"Section heading.
descriptionstring"Browse by album, or view everything at once."Supporting copy under the heading.
itemsAlbumItem[]noneEvery photo across every album; the filter pills and "All" view are both derived from this one list.
classNamestringundefinedExtra classes for the outer section element.

Types

interface AlbumItem {
  image?: { src: string; alt: string };
  title: string;
  album: string;
}

Behavior notes

  • Real client-side state: `activeAlbum` (string, default "All") drives a `useMemo`-filtered list of `items` by matching `album`; the pill row is built from the distinct album names found in `items` plus a fixed "All" pill, so it stays in sync with whatever data is passed in.
  • Real client-side state: `openIndex` (number | null) indexes into the currently filtered list (not the full `items` array), so prev/next and the thumbnail index only ever step through the photos the visitor can currently see in the grid.
  • The full-screen viewer is deliberately light (bg-background / bg-muted/30), not a dark scrim: the photo sits on the ordinary page surface, matching this block's brief of a plain, gallery-app-style viewer rather than a cinematic lightbox.
  • The viewer supports ArrowLeft/ArrowRight/Escape via a keydown listener registered in useEffect only while it's open, removed on close.
  • The side column's numbered list is a real thumbnail index: each row is a button with a small MediaSlot thumbnail, a zero-padded number, and the photo's title, and clicking any row jumps `openIndex` straight to it.
  • "use client" component, so its demo props live in the sibling gallery22.demo.tsx file per this repo's client/demo-file-split rule, not in gallery22.tsx itself.