Filmstrip Stage Viewer

Gallery5: Filmstrip Stage Viewer

One picture held at stage size with its caption and counter on a scrim, arrows inside the frame, and a filmstrip of every other frame underneath. The stage is the viewer, so nothing ever covers the page.

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

Base UI flavor

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

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

Quick start

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

import { Gallery5, gallery5Demo } from "@/components/beste/block/gallery5";

export default function Page() {
  return <Gallery5 {...gallery5Demo} />;
}

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

import { Gallery5 } from "@/components/beste/block/gallery5";

export default function Page() {
  return (
    <Gallery5
      badge={{ label: "Frame by frame" }}
      heading="One picture at a time, as big as the page allows."
      items={[
        {
          src: "/frames/room.jpg",
          alt: "Empty room lit by a tall window",
          caption: "Empty room, one window",
          meta: "Rotterdam, March",
        },
        {
          src: "/frames/ceiling.jpg",
          alt: "Vaulted ceiling with repeating ribs",
          caption: "Ribs, seen from below",
          meta: "Rotterdam, March",
        },
      ]}
      labels={{ previousLabel: "Previous frame", nextLabel: "Next frame", counterSeparator: "of" }}
    />
  );
}

Props

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

type Gallery5Labels = {
  previousLabel?: string;
  nextLabel?: string;
  counterSeparator?: string;
};

Behavior notes

• The stage itself is the viewer: there is no overlay to open, so the caption, counter and controls all live inside the picture and the page never gets covered.
• Caption and counter sit on a bottom gradient scrim rather than a full wash, so the top of the photograph stays untouched.
• Filmstrip thumbnails are grow basis-28 (and md:basis-40), which is what makes a short set stretch to fill the row instead of leaving a gap at the end, while a long set wraps onto a second line.
• The current thumbnail is at full opacity and the rest sit at opacity-40, marking the position without a border or a colour.
• Every thumbnail is a real button with aria-pressed and an aria-label carrying its caption, so the strip is navigable rather than decorative.
• Step controls only render when there is more than one frame, and stepping wraps in both directions.
• The stage switches ratio rather than height (aspect-[4/3] becoming md:aspect-[21/9]), so it stays cinematic on desktop without going letterbox-thin on a phone.