IMAGE GALLERY

Focus Stack.

A fanned stack of images. Selecting one brings it to the front and shows its caption and link.

Studio archive 01 / 03
Two interlocking silver and glass loops suspended above a pale blue surface.

Two interlocking loops in silver and glass. Select another image to bring it forward.

REACT + TYPESCRIPT + CSSMIT LICENSE

Installation

In a project with React and shadcn configured, run:

npx shadcn@latest add https://aduneer.github.io/opalframe/r/focus-stack.json

Copies the component and its stylesheet into components/ui. No additional runtime dependencies. Tailwind classes work through className.

For manual installation, copy both files from Source below. Keep the CSS import alongside the component.

Usage

import { FocusStack } from "@/components/ui/focus-stack";

export default function Example() {
  return (
    <FocusStack
      label="Selected projects"
      defaultExpanded
      items={[
        { id: "identity", title: "Studio identity", image: "/images/identity.jpg",
          alt: "A silver identity system on pale blue stationery.",
          description: "Logo, type, and stationery.", href: "/work/identity" },
        { id: "space", title: "A quiet space", image: "/images/space.jpg",
          alt: "A bright architectural interior with glass partitions.",
          description: "Interior design for a small office.", href: "/work/space" },
        { id: "object", title: "Small objects", image: "/images/object.jpg",
          alt: "A porcelain object casting a soft shadow.",
          description: "Product photography.", href: "/work/object" },
      ]}
    />
  );
}

Customize

Colors and sizes are scoped CSS variables. Override them on your own class.

<FocusStack items={yourProjects} className="your-stack" aspectRatio={4 / 5} />

.your-stack {
  --stack-accent: #a6cfff;
  --stack-surface: #1e2530;
  --stack-selected: #293449;
  --stack-text: #f2f5fa;
  --stack-muted: #aebdcc;
  --stack-line: #3f4f64;
}

Props

PropTypeWhat it does
itemsFocusStackItem[]Unique id, title, image URL, descriptive alt, and optional description/href. Supply your own images and their rights. Empty collections render nothing.
value / defaultValuestringControlled or initial selected image ID. A removed or unknown selection falls back to the first item.
onValueChange(id: string) => voidCalled when a different image is selected. Update value in controlled mode.
defaultExpandedbooleanStart with a fanned overview; defaults false. Visitors can stack or spread the deck.
aspectRationumberImage width divided by height, default 4/5. Images use object-fit cover.
labelstringVisible and accessible collection name; default Image collection.
className / reducedMotionstring / booleanScoped customization and a static selection transition. The OS motion preference is respected too.

Accessibility & motion

Image selection uses native tabs with Arrow Left/Right, Home, and End. The selected image has a described panel; captions announce politely. Exposed back cards are pointer/touch selectors, with keyboard equivalents in the tabs. Project links remain native. Caption descriptions reserve the largest text footprint. No autoplay, drag interception, animation loop, or focus changes occur during pointer selection. Reduced motion removes transitions.

Dependencies

React only. Styles live in a plain CSS file next to the component, and Tailwind utilities work through className.

Source

focus-stack.tsx
"use client";

import { useId, useState, type CSSProperties, type KeyboardEvent } from "react";
import "./focus-stack.css";

export interface FocusStackItem {
  id: string;
  title: string;
  image: string;
  alt: string;
  description?: string;
  href?: string;
}

export interface FocusStackProps {
  items: FocusStackItem[];
  value?: string;
  defaultValue?: string;
  onValueChange?: (id: string) => void;
  defaultExpanded?: boolean;
  /** Image width divided by height; defaults to 4/5. */
  aspectRatio?: number;
  label?: string;
  className?: string;
  reducedMotion?: boolean;
}

/** A fanned image collection, with selection and captions outside the artwork. */
export function FocusStack({
  items,
  value,
  defaultValue,
  onValueChange,
  defaultExpanded = false,
  aspectRatio = 4 / 5,
  label = "Image collection",
  className = "",
  reducedMotion = false,
}: FocusStackProps) {
  const uid = useId();
  const [internal, setInternal] = useState(defaultValue ?? items[0]?.id);
  const [expanded, setExpanded] = useState(defaultExpanded);
  const selected =
    items.find((item) => item.id === (value ?? internal)) ?? items[0];
  if (!selected) return null;
  const index = items.indexOf(selected);
  const ratio =
    Number.isFinite(aspectRatio) && aspectRatio > 0 ? aspectRatio : 4 / 5;

  function select(id: string) {
    if (id === selected.id) return;
    if (value === undefined) setInternal(id);
    onValueChange?.(id);
  }

  function navigate(event: KeyboardEvent<HTMLButtonElement>, current: number) {
    let next = current;
    if (event.key === "ArrowRight") next = (current + 1) % items.length;
    else if (event.key === "ArrowLeft")
      next = (current - 1 + items.length) % items.length;
    else if (event.key === "Home") next = 0;
    else if (event.key === "End") next = items.length - 1;
    else return;
    event.preventDefault();
    select(items[next].id);
    document.getElementById(`${uid}-tab-${items[next].id}`)?.focus();
  }

  return (
    <section
      className={`is-focus-stack ${className}`}
      aria-label={label}
      data-expanded={expanded}
      data-reduced-motion={reducedMotion || undefined}
      style={
        {
          "--stack-ratio": ratio,
          "--stack-spread-steps": Math.max(
            2,
            Math.min(4, Math.floor(items.length / 2) * 2),
          ),
        } as CSSProperties
      }
    >
      <div className="is-focus-stack-heading">
        <span>
          {label}{" "}
          <span>
            {String(index + 1).padStart(2, "0")} /{" "}
            {String(items.length).padStart(2, "0")}
          </span>
        </span>
        {items.length > 1 && (
          <button
            type="button"
            aria-expanded={expanded}
            aria-controls={`${uid}-panel`}
            onClick={() => setExpanded(!expanded)}
          >
            <span aria-hidden="true">{expanded ? "↙" : "↗"}</span>{" "}
            {expanded ? "Stack the deck" : "Spread the deck"}
          </button>
        )}
      </div>
      <div
        className="is-focus-stack-stage"
        id={`${uid}-panel`}
        role="tabpanel"
        aria-labelledby={`${uid}-tab-${selected.id}`}
        tabIndex={0}
      >
        {items.map((item, itemIndex) => {
          let offset = itemIndex - index;
          if (offset > items.length / 2) offset -= items.length;
          if (offset < -items.length / 2) offset += items.length;
          const distance = Math.abs(offset);
          return (
            <button
              className="is-focus-stack-card"
              type="button"
              key={item.id}
              tabIndex={-1}
              aria-label={`Show ${item.title}`}
              aria-pressed={item.id === selected.id}
              aria-describedby={
                item.id === selected.id ? `${uid}-image-description` : undefined
              }
              hidden={distance > 2}
              onClick={() => select(item.id)}
              style={
                {
                  "--stack-offset": offset,
                  "--stack-distance": distance,
                  zIndex: items.length - distance,
                } as CSSProperties
              }
            >
              {/* Image text is described by the selected panel; back cards are visual selectors. */}
              <img
                src={item.image}
                alt=""
                loading={item.id === selected.id ? "eager" : "lazy"}
                draggable={false}
              />
              <span className="is-focus-stack-card-label" aria-hidden="true">
                {item.title} <span>↗</span>
              </span>
            </button>
          );
        })}
        <span className="is-focus-stack-sr" id={`${uid}-image-description`}>
          {selected.alt}
        </span>
      </div>
      <div
        className="is-focus-stack-tabs"
        role="tablist"
        aria-label="Choose an image"
      >
        {items.map((item, itemIndex) => (
          <button
            type="button"
            role="tab"
            key={item.id}
            id={`${uid}-tab-${item.id}`}
            aria-selected={selected.id === item.id}
            aria-controls={`${uid}-panel`}
            tabIndex={selected.id === item.id ? 0 : -1}
            onClick={() => select(item.id)}
            onKeyDown={(event) => navigate(event, itemIndex)}
          >
            <span>{String(itemIndex + 1).padStart(2, "0")}</span> {item.title}
          </button>
        ))}
      </div>
      <div
        className="is-focus-stack-caption"
        aria-live="polite"
        aria-atomic="true"
      >
        <div className="is-focus-stack-descriptions">
          {items.map((item) => (
            <p
              key={item.id}
              data-active={item.id === selected.id}
              aria-hidden={item.id !== selected.id}
            >
              {item.description}
            </p>
          ))}
        </div>
        <div className="is-focus-stack-link">
          {selected.href && (
            <a href={selected.href}>
              View project <span aria-hidden="true">↗</span>
            </a>
          )}
        </div>
      </div>
    </section>
  );
}
focus-stack.css
.is-focus-stack {
  --stack-accent: var(--accent, #aacfff);
  --stack-text: var(--text, #f0f3f8);
  --stack-muted: var(--muted, #adb7c6);
  --stack-line: var(--line, #343d4a);
  --stack-surface: var(--surface, #181d25);
  --stack-card-width: clamp(120px, 46cqw, 280px);
  --stack-spread: 16px;
  width: 100%;
  min-width: 0;
  container-type: inline-size;
  color: var(--stack-text);
}
.is-focus-stack-heading {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 16px;
  padding-bottom: 12px;
  font-size: 12px;
}
.is-focus-stack-heading > span > span {
  margin-left: 12px;
  color: var(--stack-muted);
  font:
    10px ui-monospace,
    monospace;
  white-space: nowrap;
}
.is-focus-stack-heading > button {
  display: inline-flex;
  align-items: center;
  gap: 8px;
  min-height: 36px;
  padding: 8px 10px;
  border: 1px solid var(--stack-line);
  border-radius: 6px;
  color: var(--stack-muted);
  background: transparent;
  font: inherit;
  font-size: 11px;
  cursor: pointer;
  white-space: nowrap;
}
.is-focus-stack-stage {
  position: relative;
  height: calc(var(--stack-card-width) / var(--stack-ratio) + 100px);
  isolation: isolate;
  perspective: 1000px;
  border-radius: 14px;
}
.is-focus-stack[data-expanded="true"] .is-focus-stack-stage {
  --stack-spread: clamp(
    0px,
    calc((100cqw - var(--stack-card-width) - 44px) / var(--stack-spread-steps)),
    140px
  );
}
.is-focus-stack-card {
  position: absolute;
  top: 50%;
  left: 50%;
  width: var(--stack-card-width);
  height: calc(var(--stack-card-width) / var(--stack-ratio));
  aspect-ratio: var(--stack-ratio);
  padding: 4px;
  border: 1px solid color-mix(in srgb, var(--stack-text) 30%, transparent);
  border-radius: 15px;
  background: color-mix(in srgb, var(--stack-surface) 88%, transparent);
  color: var(--stack-text);
  box-shadow:
    0 4px 8px #00000010,
    0 22px 38px -20px #00000055;
  transform: translate(-50%, -50%)
    translateX(calc(var(--stack-offset) * var(--stack-spread)))
    translateY(calc(var(--stack-distance) * -10px))
    rotate(calc(var(--stack-offset) * 7deg))
    rotateY(calc(var(--stack-offset) * -8deg))
    scale(calc(1 - var(--stack-distance) * 0.06));
  transition:
    transform 650ms cubic-bezier(0.22, 1, 0.36, 1),
    border-color 200ms,
    box-shadow 250ms;
  cursor: pointer;
}
.is-focus-stack-card[hidden] {
  display: none;
}
.is-focus-stack-card img {
  display: block;
  width: 100%;
  height: 100%;
  border-radius: 10px;
  object-fit: cover;
  pointer-events: none;
  user-select: none;
}
.is-focus-stack-card::after {
  content: "";
  position: absolute;
  inset: 4px;
  border-radius: 10px;
  background: linear-gradient(
    125deg,
    #ffffff30,
    transparent 35%,
    transparent 70%,
    #ffffff18
  );
  pointer-events: none;
}
.is-focus-stack-card[aria-pressed="true"] {
  border-color: color-mix(in srgb, var(--stack-accent) 65%, var(--stack-line));
  box-shadow:
    0 5px 12px #00000012,
    0 32px 54px -26px #00000070;
}
.is-focus-stack-card:hover {
  border-color: var(--stack-accent);
}
.is-focus-stack-card-label {
  position: absolute;
  bottom: 14px;
  left: 14px;
  right: 14px;
  display: flex;
  justify-content: space-between;
  gap: 8px;
  padding: 10px 12px;
  border: 1px solid #ffffff35;
  border-radius: 6px;
  background: var(--stack-surface);
  color: var(--stack-text);
  font:
    11px system-ui,
    sans-serif;
}
.is-focus-stack-tabs {
  display: flex;
  justify-content: center;
  flex-wrap: wrap;
  gap: 6px;
}
.is-focus-stack-tabs button {
  display: flex;
  align-items: center;
  gap: 8px;
  min-height: 40px;
  padding: 9px 12px;
  border: 1px solid transparent;
  border-radius: 7px;
  background: transparent;
  color: var(--stack-muted);
  font: inherit;
  font-size: 12px;
  cursor: pointer;
}
.is-focus-stack-tabs button > span {
  font:
    9px ui-monospace,
    monospace;
  color: inherit;
}
.is-focus-stack-tabs button[aria-selected="true"] {
  background: var(--stack-selected, var(--stack-surface));
  border-color: var(--stack-line);
  color: var(--stack-text);
}
.is-focus-stack-caption {
  display: flex;
  align-items: flex-start;
  justify-content: space-between;
  gap: 16px;
  padding-top: 18px;
  color: var(--stack-muted);
  font-size: 12px;
  line-height: 1.7;
}
.is-focus-stack-descriptions {
  display: grid;
  flex: 1;
  min-width: 0;
}
.is-focus-stack-descriptions > p {
  grid-area: 1/1;
  margin: 0;
}
.is-focus-stack-descriptions > p[data-active="false"] {
  visibility: hidden;
}
.is-focus-stack-caption a {
  flex-shrink: 0;
  color: var(--stack-text);
  text-decoration: none;
}
.is-focus-stack-caption a > span {
  margin-left: 6px;
  color: var(--stack-accent);
}
.is-focus-stack-link {
  min-height: 1.7em;
  flex-shrink: 0;
}
.is-focus-stack button:focus-visible,
.is-focus-stack a:focus-visible,
.is-focus-stack-stage:focus-visible {
  outline: 2px solid var(--stack-accent);
  outline-offset: 4px;
}
.is-focus-stack-sr {
  position: absolute;
  width: 1px;
  height: 1px;
  overflow: hidden;
  clip-path: inset(50%);
  white-space: nowrap;
}
@container (max-width: 380px) {
  .is-focus-stack-heading {
    flex-wrap: wrap;
    gap: 8px;
    font-size: 11px;
  }
  .is-focus-stack-caption {
    flex-direction: column;
    gap: 12px;
  }
  .is-focus-stack-tabs button {
    font-size: 11px;
    padding: 9px;
  }
  .is-focus-stack-card-label {
    padding: 7px;
    font-size: 9px;
    bottom: 10px;
    left: 10px;
    right: 10px;
  }
}
.is-focus-stack[data-reduced-motion] * {
  transition: none !important;
}
@media (prefers-reduced-motion: reduce) {
  .is-focus-stack * {
    transition: none !important;
  }
}