# Stack Panel
> A panel that drills into pages like settings on a phone. The tapped row's label flies up into the title, and a swipe right takes you back.

Source: https://kokonutui.com/docs/navigation/stack-panel

## Installation

```bash
npx shadcn@latest add @kokonutui/stack-panel
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className?` | `string` |  | Extra classes for the root element. |

## Source

```tsx
"use client";

/**
 * @author: @dorianbaffier
 * @description: Stack Panel
 * @version: 1.0.0
 * @date: 2026-10-16
 * @license: MIT
 * @website: https://kokonutui.com
 * @github: https://github.com/kokonut-labs/kokonutui
 */

import { Check, ChevronLeft, ChevronRight } from "lucide-react";
import { AnimatePresence, animate, MotionConfig, motion, type PanInfo, useAnimate, useMotionValue, useReducedMotion, useTransform } from "motion/react";
import { type KeyboardEvent, type ReactNode, useEffect, useLayoutEffect, useRef, useState } from "react";
import { flushSync } from "react-dom";
import { cn } from "@/lib/utils";

export interface StackRow {
  id: string;
  label: string;
  /** Grey text on the right, like the current value of a setting. */
  detail?: string;
  /** Id of the page this row opens. */
  to?: string;
  /** Anything else on the right: a switch, a badge. */
  trailing?: ReactNode;
  onSelect?: () => void;
  /** Shows a check, for rows that pick one option of a section. */
  selected?: boolean;
  /** Shows a switch in this state, for rows that turn something on. */
  checked?: boolean;
  tone?: "default" | "danger";
}

export interface StackSection {
  title?: string;
  rows: StackRow[];
  /** Small print under the section. */
  footer?: string;
}

export interface StackPage {
  title: string;
  sections: StackSection[];
}

export interface StackPanelProps {
  pages: Record<string, StackPage>;
  /** The page the panel starts on. */
  root: string;
  className?: string;
}

const PUSH = { type: "spring", duration: 0.42, bounce: 0 } as const;
const HEIGHT = { type: "spring", duration: 0.38, bounce: 0 } as const;
const EASE_OUT = [0.23, 1, 0.32, 1] as const;
const PARALLAX = 0.3;
const POP_DISTANCE = 0.35;
const POP_VELOCITY = 500;

interface Origin {
  /** The tapped row's label, relative to the panel. */
  left: number;
  top: number;
  height: number;
  fontSize: number;
}

function Title({ text, origin, direction, panel }: { text: string; origin: Origin | null; direction: 1 | -1; panel: HTMLElement | null; }) {
  const [scope, run] = useAnimate<HTMLSpanElement>();
  const reduced = useReducedMotion();

useLayoutEffect(() => {
    const el = scope.current;
    if (!(el && panel)) {
      return;
    }
    if (!origin || reduced) {
      run(el, { opacity: [0, 1], x: [direction * 24, 0] }, { duration: reduced ? 0 : 0.28, ease: EASE_OUT });
      return;
    }
    const box = panel.getBoundingClientRect();
    const own = el.getBoundingClientRect();
    const fontSize = Number.parseFloat(getComputedStyle(el).fontSize);
    const scale = origin.fontSize / fontSize;
    const dx = origin.left - (own.left - box.left);
    const dy = origin.top + origin.height / 2 - (own.top - box.top + own.height / 2);
    el.style.transform = `translateX(${dx}px) translateY(${dy}px) scale(${scale})`;
    run(el, { x: [dx, 0], y: [dy, 0], scale: [scale, 1], opacity: [1, 1] }, PUSH);
  }, [scope, run, origin, direction, panel, reduced]);

return (
    <motion.span className="absolute inset-x-0 top-1/2 mx-auto w-fit max-w-[55%] -translate-y-1/2 truncate font-semibold text-[15px] text-zinc-900 dark:text-zinc-100" exit={{ opacity: 0, x: direction * -40, transition: { duration: 0.18, ease: EASE_OUT } }} ref={scope} style={{ transformOrigin: "left center" }}>
      {text}
    </motion.span>
  );
}

function Page({ page, onOpen, measureRef }: { page: StackPage; onOpen: (row: StackRow, label: HTMLElement) => void; measureRef?: (el: HTMLDivElement | null) => void; }) {
  return (
    <div className="flex flex-col gap-5 px-3 pt-2 pb-4" ref={measureRef}>
      {page.sections.map((section, index) => (
        <section key={index}>
          {section.title && (
            <h3 className="mb-1.5 px-3 font-medium text-xs text-zinc-500 dark:text-zinc-400">
              {section.title}
            </h3>
          )}
          <ul className="divide-y divide-zinc-100 overflow-hidden rounded-xl bg-zinc-50 dark:divide-zinc-800/70 dark:bg-zinc-900">
            {section.rows.map((row) => (
              <li key={row.id}>
                <RowView onOpen={onOpen} row={row} />
              </li>
            ))}
          </ul>
          {section.footer && (
            <p className="mt-1.5 px-3 text-xs text-zinc-400 leading-5 dark:text-zinc-500">
              {section.footer}
            </p>
          )}
        </section>
      ))}
    </div>
  );
}

function RowView({ row, onOpen }: { row: StackRow; onOpen: (row: StackRow, label: HTMLElement) => void; }) {
  const labelRef = useRef<HTMLSpanElement>(null);
  const interactive = Boolean(row.to || row.onSelect);
  const content = (
    <>
      <span className={cn("min-w-0 flex-1 truncate text-left text-[15px]", row.tone === "danger" ? "text-red-600 dark:text-red-400" : "text-zinc-900 dark:text-zinc-100")} ref={labelRef}>
        {row.label}
      </span>
      {row.detail && (<span className="max-w-[45%] shrink-0 truncate text-sm text-zinc-500 dark:text-zinc-400">{row.detail}</span>)}
      {row.trailing}
      {row.checked !== undefined && <Toggle on={row.checked} />}
      {row.selected !== undefined && <Check aria-hidden="true" className={cn("size-4 shrink-0 text-zinc-900 dark:text-zinc-100", !row.selected && "invisible")} />}
      {row.to && <ChevronRight aria-hidden="true" className="-mr-1 size-4 shrink-0 text-zinc-400 dark:text-zinc-500" />}
    </>
  );
  const base = "flex min-h-11 w-full items-center gap-2 px-3 py-2";
  if (!interactive) {
    return <div className={base}>{content}</div>;
  }
  const className = cn(base, "outline-none transition-colors duration-150 hover:bg-zinc-100 focus-visible:bg-zinc-100 active:bg-zinc-100 dark:active:bg-zinc-800 dark:focus-visible:bg-zinc-800 dark:hover:bg-zinc-800/60");
  const onClick = () => {
    if (labelRef.current) {
      onOpen(row, labelRef.current);
    }
  };
  if (row.checked !== undefined) {
    return (
      <button aria-checked={row.checked} className={className} data-row={row.id} onClick={onClick} role="switch" type="button">
        {content}
      </button>
    );
  }
  return (
    <button aria-pressed={row.selected} className={className} data-row={row.id} onClick={onClick} type="button">
      {content}
    </button>
  );
}

export function StackPanel({ pages, root, className }: StackPanelProps) {
  const [stack, setStack] = useState<string[]>([root]);
  const [origin, setOrigin] = useState<Origin | null>(null);
  const [direction, setDirection] = useState<1 | -1>(1);
  const [height, setHeight] = useState<number | "auto">("auto");
  const [busy, setBusy] = useState(false);
  const panelRef = useRef<HTMLDivElement>(null);
  const bodyRef = useRef<HTMLDivElement>(null);
  const backRef = useRef<HTMLButtonElement>(null);
  const observer = useRef<ResizeObserver | null>(null);
  const openers = useRef<string[]>([]);
  const x = useMotionValue(0);
  const [width, setWidth] = useState(360);
  const underX = useTransform(x, (v) => -PARALLAX * (width - v));
  const shade = useTransform(x, [0, width], [0.06, 0]);

const top = stack.at(-1) ?? root;
  const under = stack.length > 1 ? stack.at(-2) : undefined;
  const parent = under ? pages[under] : undefined;

useEffect(() => {
    const body = bodyRef.current;
    if (!body) {
      return;
    }
    const watch = new ResizeObserver(() => setWidth(body.clientWidth));
    watch.observe(body);
    return () => {
      watch.disconnect();
      observer.current?.disconnect();
    };
  }, []);

const measure = (el: HTMLDivElement | null) => {
    observer.current?.disconnect();
    if (!el) {
      return;
    }
    observer.current = new ResizeObserver(() => setHeight(el.offsetHeight));
    observer.current.observe(el);
  };

const push = (row: StackRow, label: HTMLElement) => {
    row.onSelect?.();
    if (!(row.to && pages[row.to]) || busy) {
      return;
    }
    const box = panelRef.current?.getBoundingClientRect();
    const rect = label.getBoundingClientRect();
    setOrigin(box ? {
      left: rect.left - box.left,
      top: rect.top - box.top,
      height: rect.height,
      fontSize: Number.parseFloat(getComputedStyle(label).fontSize),
    } : null);
    setDirection(1);
    setBusy(true);
    x.set(width);
    const to = row.to;
    openers.current.push(row.id);
    flushSync(() => setStack((s) => [...s, to]));
    animate(x, 0, PUSH).then(() => setBusy(false));
    backRef.current?.focus({ preventScroll: true });
  };

const pop = () => {
    if (stack.length < 2 || busy) {
      return;
    }
    setOrigin(null);
    setDirection(-1);
    setBusy(true);
    const opener = openers.current.pop();
    const hadFocus = panelRef.current?.contains(document.activeElement);
    animate(x, width, { ...PUSH, duration: 0.34 }).then(() => {
      flushSync(() => setStack((s) => s.slice(0, -1)));
      x.set(0);
      setBusy(false);
      if (hadFocus && opener) {
        const rows = bodyRef.current?.querySelectorAll<HTMLElement>(`[data-row="${CSS.escape(opener)}`]");
        const row = [...(rows ?? [])].find((el) => !el.closest("[inert]"));
        row?.focus({ preventScroll: true });
      }
    });
  };

const onDragEnd = (_: unknown, info: PanInfo) => {
    if (x.get() > width * POP_DISTANCE || info.velocity.x > POP_VELOCITY) {
      pop();
    } else {
      animate(x, 0, PUSH);
    }
  };

const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
    if (event.key === "Escape" && stack.length > 1) {
      event.preventDefault();
      pop();
    }
  };

return (
    <MotionConfig reducedMotion="user">
      <div className={cn("relative w-full max-w-sm overflow-hidden rounded-2xl border border-zinc-200 bg-white dark:border-zinc-800 dark:bg-zinc-950", className)} onKeyDown={onKeyDown} ref={panelRef}>
        <div className="relative z-10 flex h-12 items-center border-zinc-100 border-b bg-white px-2 dark:border-zinc-900 dark:bg-zinc-950">
          <AnimatePresence initial={false}>
            {parent && (
              <motion.button animate={{ opacity: 1 }} className="relative z-10 flex max-w-[30%] items-center rounded-lg py-1.5 pr-2 pl-1 text-sm text-zinc-600 outline-none transition-colors duration-150 hover:bg-zinc-100 hover:text-zinc-900 focus-visible:ring-2 focus-visible:ring-zinc-400 dark:text-zinc-400 dark:hover:bg-zinc-900 dark:hover:text-zinc-100" exit={{ opacity: 0 }} initial={{ opacity: 0 }} key="back" onClick={pop} ref={backRef} transition={{ duration: 0.18 }} type="button">
                <ChevronLeft aria-hidden="true" className="size-4 shrink-0" />
                <span className="truncate">{parent.title}</span>
              </motion.button>
            )}
          </AnimatePresence>
          <AnimatePresence initial={false}>
            <Title direction={direction} key={`${top}-${stack.length}`} origin={origin} panel={panelRef.current} text={pages[top]?.title ?? ""} />
          </AnimatePresence>
        </div>

<motion.div animate={{ height }} className="relative" ref={bodyRef} transition={HEIGHT}>
          {under && pages[under] && (
            <motion.div aria-hidden="true" className="pointer-events-none absolute inset-x-0 top-0" inert key={`${under}-${stack.length - 1}`} style={{ x: underX }}>
              <Page onOpen={() => undefined} page={pages[under]} />
              <motion.div className="absolute inset-0 bg-black" style={{ opacity: shade }} />
            </motion.div>
          )}
          {pages[top] && (
            <motion.div className="relative bg-white dark:bg-zinc-950" drag={stack.length > 1 && !busy ? "x" : false} dragConstraints={{ left: 0, right: 0 }} dragDirectionLock dragElastic={{ left: 0, right: 1 }} dragMomentum={false} key={`${top}-${stack.length}`} onDragEnd={onDragEnd} style={{ x, boxShadow: stack.length > 1 ? "-8px 0 24px -12px rgb(0 0 0 / 0.18)" : "" }}>
              <Page measureRef={measure} onOpen={push} page={pages[top]} />
            </motion.div>
          )}
        </motion.div>
      </div>
    </MotionConfig>
  );
}

function Toggle({ on }: { on: boolean }) {
  return (
    <span aria-hidden="true" className={cn("relative h-[22px] w-9 shrink-0 rounded-full transition-colors duration-200", on ? "bg-zinc-900 dark:bg-zinc-100" : "bg-zinc-200 dark:bg-zinc-700")}> 
      <span className={cn("absolute top-0.5 left-0.5 size-[18px] rounded-full bg-white shadow-sm transition-transform duration-200 ease-[cubic-bezier(0.23,1,0.32,1)] dark:bg-zinc-950", on && "translate-x-3.5")} />
    </span>
  );
}

/** Workspace settings, three levels deep. */
export default function StackPanelDemo({ className }: { className?: string }) {
  const [theme, setTheme] = useState("System");
  const [density, setDensity] = useState("Comfortable");
  const [alerts, setAlerts] = useState({
    mentions: true,
    digest: false,
    deploys: true,
  });
  const [quiet, setQuiet] = useState("22:00 – 07:00");

const flip = (key: keyof typeof alerts) => () =>
    setAlerts((a) => ({ ...a, [key]: !a[key] }));
  const toggleRow = (id: keyof typeof alerts, label: string): StackRow => ({
    id,
    label,
    onSelect: flip(id),
    checked: alerts[id],
  });
  const choice = (
    value: string,
    current: string,
    set: (v: string) => void
  ): StackRow => ({
    id: value,
    label: value,
    selected: value === current,
    onSelect: () => set(value),
  });

const pages: Record<string, StackPage> = {
    settings: {
      title: "Settings",
      sections: [
        {
          rows: [
            {
              id: "account",
              label: "Account",
              detail: "Maya Chen",
              to: "account",
            },
            {
              id: "appearance",
              label: "Appearance",
              detail: theme,
              to: "appearance",
            },
            {
              id: "notifications",
              label: "Notifications",
              to: "notifications",
            },
          ],
        },
        {
          rows: [
            { id: "billing", label: "Billing", detail: "Pro", to: "billing" },
            { id: "shortcuts", label: "Keyboard shortcuts", detail: "34" },
          ],
        },
      ],
    },
    account: {
      title: "Account",
      sections: [
        {
          rows: [
            { id: "name", label: "Name", detail: "Maya Chen" },
            { id: "email", label: "Email", detail: "maya@acme.com" },
            { id: "security", label: "Password & security", to: "security" },
          ],
        },
        {
          rows: [
            {
              id: "sign-out",
              label: "Sign out",
              tone: "danger",
              onSelect: () => undefined,
            },
          ],
        },
      ],
    },
    security: {
      title: "Password & security",
      sections: [
        {
          rows: [
            {
              id: "password",
              label: "Password",
              detail: "Changed 3 months ago",
            },
            { id: "2fa", label: "Two-factor", detail: "Authenticator app" },
            { id: "sessions", label: "Active sessions", detail: "3" },
          ],
          footer: "Signing out of a session takes effect on its next request.",
        },
      ],
    },
    appearance: {
      title: "Appearance",
      sections: [
        {
          title: "Theme",
          rows: ["Light", "Dark", "System"].map((v) =>
            choice(v, theme, setTheme)
          ),
        },
        {
          title: "Density",
          rows: ["Comfortable", "Compact"].map((v) =>
            choice(v, density, setDensity)
          ),
        },
      ],
    },
    notifications: {
      title: "Notifications",
      sections: [
        {
          rows: [
            toggleRow("mentions", "Mentions"),
            toggleRow("deploys", "Failed deploys"),
            toggleRow("digest", "Weekly digest"),
          ],
        },
        {
          rows: [
            { id: "quiet", label: "Quiet hours", detail: quiet, to: "quiet" },
          ],
          footer: "Nothing but failed deploys gets through in quiet hours.",
        },
      ],
    },
    quiet: {
      title: "Quiet hours",
      sections: [
        {
          rows: ["Off", "22:00 – 07:00", "20:00 – 09:00", "Weekends"].map((v) =>
            choice(v, quiet, setQuiet)
          ),
        },
      ],
    },
    billing: {
      title: "Billing",
      sections: [
        {
          rows: [
            { id: "plan", label: "Plan", detail: "Pro, yearly" },
            { id: "next", label: "Next invoice", detail: "Nov 1 · $96" },
            { id: "card", label: "Card", detail: "Visa ·· 4242" },
          ],
        },
      ],
    },
  };

return <StackPanel className={className} pages={pages} root="settings" />;
}
