save button.md
Save Button
A bookmark button that files into collections. Tap to save to the last one, then change it or make a new one from the strip.
Source: https://kokonutui.com/docs/buttons/save-button
Installation
npx shadcn@latest add @kokonutui/save-button
Props
| Prop | Type | Default | Description |
|---|---|---|---|
collections? |
SaveCollection[] |
built-in |
|
defaultCollection? |
string |
Where a tap saves to, by id. Defaults to the first collection. | |
defaultSaved? |
boolean |
false |
|
onSave? |
(collectionId: string) => void |
||
onMove? |
(collectionId: string) => void |
||
onRemove? |
() => void |
||
className? |
string |
Extra classes for the root element. |
SaveCollection
| Field | Type | Description |
|---|---|---|
id |
string |
|
name |
string |
|
count |
number |
Items already in it, before this one. |
color |
string |
Tailwind background class for its swatch. |
Source
"use client";
/**
* @author: @dorianbaffier
* @description: Save Button
* @version: 1.0.0
* @date: 2026-10-21
* @license: MIT
* @website: https://kokonutui.com
* @github: https://github.com/kokonut-labs/kokonutui
*/
import { Check, Plus } from "lucide-react";
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
import {
type FormEvent,
useEffect,
useId,
useLayoutEffect,
useRef,
useState,
} from "react";
import { cn } from "@/lib/utils";
const EASE_OUT = [0.23, 1, 0.32, 1] as const;
/** How long the "Saved to" strip stays up when left alone. */
const STRIP_FOR = 4000;
export interface SaveCollection {
id: string;
name: string;
/** Items already in it, before this one. */
count: number;
/** Tailwind background class for its swatch. */
color: string;
}
export interface SaveButtonProps {
collections?: SaveCollection[];
/** Where a tap saves to, by id. Defaults to the first collection. */
defaultCollection?: string;
defaultSaved?: boolean;
onSave?: (collectionId: string) => void;
onMove?: (collectionId: string) => void;
onRemove?: () => void;
className?: string;
}
const DEFAULT_COLLECTIONS: SaveCollection[] = [
{ id: "weekend", name: "Weekend trips", count: 12, color: "bg-orange-400" },
{ id: "tokyo", name: "Tokyo 2027", count: 31, color: "bg-sky-400" },
{ id: "food", name: "Places to eat", count: 48, color: "bg-emerald-400" },
{ id: "someday", name: "Someday", count: 7, color: "bg-violet-400" },
];
const SWATCHES = [
"bg-rose-400",
"bg-amber-300",
"bg-teal-400",
"bg-indigo-400",
];
type View = "closed" | "saved" | "picking" | "removed";
// The panel sits under AnimatePresence, so it's found by query, not ref.
const findPanel = (root: HTMLElement | null) =>
root?.querySelector("[data-save-panel]") ?? null;
const focusInPanel = (root: HTMLElement | null) =>
Boolean(findPanel(root)?.contains(document.activeElement));
// Whatever closes or swaps the panel's content would drop focus on <body>,
// so it goes back to the button first.
const returnFocus = (root: HTMLElement | null, button: HTMLElement | null) => {
if (focusInPanel(root)) {
button?.focus();
}
};
/** A bookmark whose ink drops in from the top like a ribbon when saved. */
function Ribbon({
saved,
reduceMotion,
}: {
saved: boolean;
reduceMotion: boolean;
}) {
const clip = useId();
let ribbonTransition: object = { duration: 0.18, ease: EASE_OUT };
if (reduceMotion) {
ribbonTransition = { duration: 0 };
} else if (saved) {
ribbonTransition = { type: "spring", stiffness: 520, damping: 24 };
}
return (
<svg
aria-hidden
className="size-4 overflow-visible"
fill="none"
viewBox="0 0 16 16"
>
<title>Bookmark</title>
<defs>
<clipPath id={clip}>
<path d="M3.5 2.5a1 1 0 0 1 1-1h7a1 1 0 0 1 1 1v11.2l-4.5-3-4.5 3z" />
</clipPath>
</defs>
<g clipPath={`url(#${clip})`}>
<motion.rect
animate={{ y: saved ? 0 : -16 }}
className="fill-current"
height="16"
initial={false}
transition={ribbonTransition}
width="16"
x="0"
y="0"
/>
</g>
<path
className="stroke-current"
d="M3.5 2.5a1 1 0 0 1 1-1h7a1 1 0 0 1 1 1v11.2l-4.5-3-4.5 3z"
strokeLinejoin="round"
strokeWidth="1.5"
/>
</svg>
);
}
export default function SaveButton({
collections: initialCollections = DEFAULT_COLLECTIONS,
defaultCollection,
defaultSaved = false,
onSave,
onMove,
onRemove,
className,
}: SaveButtonProps) {
const [collections, setCollections] = useState(initialCollections);
const [savedTo, setSavedTo] = useState<string | null>(
defaultSaved
? (defaultCollection ?? initialCollections[0]?.id ?? null)
: null
);
const [lastUsed, setLastUsed] = useState(
defaultCollection ?? initialCollections[0]?.id ?? ""
);
const [view, setView] = useState<View>("closed");
const [draft, setDraft] = useState("");
const [moved, setMoved] = useState(false);
const reduceMotion = Boolean(useReducedMotion());
const rootRef = useRef<HTMLDivElement>(null);
const buttonRef = useRef<HTMLButtonElement>(null);
const hoverRef = useRef(false);
const timerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
const contentRef = useRef<HTMLDivElement>(null);
const isOpen = view !== "closed";
const [contentHeight, setContentHeight] = useState<number>();
// The strip grows into the picker and back by its measured height.
useLayoutEffect(() => {
const content = contentRef.current;
if (!(isOpen && content)) {
setContentHeight(undefined);
return;
}
const observer = new ResizeObserver(() =>
setContentHeight(content.offsetHeight)
);
observer.observe(content);
return () => observer.disconnect();
}, [isOpen]);
const saved = savedTo !== null;
const current = collections.find((c) => c.id === savedTo);
// The strip closes on its own unless it is being read or used.
const schedule = (ms = STRIP_FOR) => {
clearTimeout(timerRef.current);
timerRef.current = setTimeout(() => {
if (!(hoverRef.current || focusInPanel(rootRef.current))) {
setView((v) => (v === "picking" ? v : "closed"));
}
}, ms);
};
useEffect(() => () => clearTimeout(timerRef.current), []);
useEffect(() => {
if (view === "closed") {
return;
}
const onPointer = (event: PointerEvent) => {
if (!rootRef.current?.contains(event.target as Node)) {
setView("closed");
}
};
const onKey = (event: KeyboardEvent) => {
if (event.key === "Escape") {
returnFocus(rootRef.current, buttonRef.current);
setView("closed");
}
};
document.addEventListener("pointerdown", onPointer);
document.addEventListener("keydown", onKey);
return () => {
document.removeEventListener("pointerdown", onPointer);
document.removeEventListener("keydown", onKey);
};
}, [view]);
// Opening the picker moves focus onto the collection it's saved in.
useEffect(() => {
if (view === "picking") {
findPanel(rootRef.current)
?.querySelector<HTMLButtonElement>('[aria-current="true"]')
?.focus();
}
}, [view]);
const toggle = () => {
if (saved) {
setSavedTo(null);
setView("removed");
onRemove?.();
schedule(1600);
return;
}
setSavedTo(lastUsed);
setMoved(false);
setView("saved");
onSave?.(lastUsed);
schedule();
};
const moveTo = (id: string) => {
returnFocus(rootRef.current, buttonRef.current);
setSavedTo(id);
setLastUsed(id);
setMoved(id !== savedTo);
setView("saved");
if (id !== savedTo) {
onMove?.(id);
}
schedule();
};
const create = (event: FormEvent) => {
event.preventDefault();
const name = draft.trim();
if (!name) {
return;
}
const id = `${name.toLowerCase().replace(/\s+/g, "-")}-${collections.length}`;
const color = SWATCHES[collections.length % SWATCHES.length];
setCollections((list) => [...list, { id, name, count: 0, color }]);
setDraft("");
moveTo(id);
};
const countFor = (collection: SaveCollection) =>
collection.count + (savedTo === collection.id ? 1 : 0);
const swap = reduceMotion
? { duration: 0 }
: { duration: 0.2, ease: EASE_OUT };
return (
<div
className={cn("relative inline-flex", className)}
onPointerEnter={() => {
hoverRef.current = true;
}}
onPointerLeave={() => {
hoverRef.current = false;
if (view === "saved" || view === "removed") {
schedule(1800);
}
}}
ref={rootRef}
>
<button
aria-pressed={saved}
className={cn(
"inline-flex h-10 items-center gap-2 rounded-full border pr-4 pl-3.5 font-medium text-sm outline-none",
"transition-colors duration-150 ease-out",
"focus-visible:ring-2 focus-visible:ring-zinc-400 focus-visible:ring-offset-2 dark:focus-visible:ring-offset-zinc-950",
saved
? "border-zinc-900 bg-zinc-900 text-white hover:bg-zinc-800 dark:border-zinc-100 dark:bg-zinc-100 dark:text-zinc-900 dark:hover:bg-white"
: "border-zinc-200 bg-white text-zinc-900 hover:bg-zinc-50 dark:border-zinc-800 dark:bg-zinc-950 dark:text-zinc-100 dark:hover:bg-zinc-900"
)}
onClick={toggle}
ref={buttonRef}
type="button"
>
<Ribbon reduceMotion={reduceMotion} saved={saved} />
<span className="relative inline-flex overflow-hidden">
<AnimatePresence initial={false} mode="popLayout">
<motion.span
animate={{ y: 0, opacity: 1 }}
exit={{ y: saved ? -14 : 14, opacity: 0 }}
initial={{ y: saved ? 14 : -14, opacity: 0 }}
key={saved ? "saved" : "save"}
transition={swap}
>
{saved ? "Saved" : "Save"}
</motion.span>
</AnimatePresence>
</span>
</button>
<AnimatePresence>
{view !== "closed" && (
<motion.div
animate={{ opacity: 1, y: 0, scale: 1 }}
className="absolute top-full left-1/2 z-20 mt-2 w-72 origin-top -translate-x-1/2 overflow-hidden rounded-2xl border border-zinc-200 bg-white shadow-[0_8px_24px_-8px_rgb(0_0_0/0.18)] dark:border-zinc-800 dark:bg-zinc-950 dark:shadow-[0_8px_24px_-8px_rgb(0_0_0/0.6)]"
data-save-panel
exit={{
opacity: 0,
y: -4,
scale: 0.98,
transition: { duration: 0.12 },
}}
initial={{ opacity: 0, y: -6, scale: 0.97 }}
transition={
reduceMotion ? { duration: 0 } : { duration: 0.2, ease: EASE_OUT }
}
>
<motion.div
animate={{ height: contentHeight ?? "auto" }}
initial={false}
transition={
reduceMotion
? { duration: 0 }
: { duration: 0.26, ease: EASE_OUT }
}
>
<div ref={contentRef}>
{view === "picking" ? (
<Picker
collections={collections}
countFor={countFor}
create={create}
draft={draft}
moveTo={moveTo}
savedTo={savedTo}
setDraft={setDraft}
/>
) : (
<div
aria-live="polite"
className="flex h-12 items-center gap-2.5 pr-2 pl-3 text-sm"
>
{view === "removed" || !current ? (
<span className="text-zinc-500 dark:text-zinc-400">
Removed from saved
</span>
) : (
<>
<span
className={cn(
"size-5 shrink-0 rounded-md",
current.color
)}
/>
<span className="min-w-0 flex-1 truncate text-zinc-500 dark:text-zinc-400">
{moved ? "Moved to " : "Saved to " }
<span className="relative inline-flex align-bottom">
<AnimatePresence initial={false} mode="popLayout">
<motion.span
animate={{ y: 0, opacity: 1 }}
className="font-medium text-zinc-900 dark:text-zinc-100"
exit={{ y: -10, opacity: 0 }}
initial={{ y: 10, opacity: 0 }}
key={current.id}
transition={swap}
>
{current.name}
</motion.span>
</AnimatePresence>
</span>
</span>
<button
className="h-8 shrink-0 rounded-full px-3 font-medium text-xs text-zinc-900 transition-colors duration-150 hover:bg-zinc-100 dark:text-zinc-100 dark:hover:bg-zinc-900"
onClick={() => {
clearTimeout(timerRef.current);
setView("picking");
}}
type="button"
>
Change
</button>
</>
)}
</div>
)}
</div>
</motion.div>
</motion.div>
)}
</AnimatePresence>
</div>
);
}
function Picker({
collections,
savedTo,
countFor,
moveTo,
draft,
setDraft,
create,
}: {
collections: SaveCollection[];
savedTo: string | null;
countFor: (collection: SaveCollection) => number;
moveTo: (id: string) => void;
draft: string;
setDraft: (value: string) => void;
create: (event: FormEvent) => void;
}) {
return (
<div className="p-1.5">
<p className="px-2 pt-1.5 pb-1 text-[11px] text-zinc-400 dark:text-zinc-500">
Save to
</p>
<ul className="max-h-56 overflow-y-auto">
{collections.map((collection) => {
const active = collection.id === savedTo;
return (
<li key={collection.id}>
<button
aria-current={active}
className="flex h-11 w-full items-center gap-2.5 rounded-xl px-2 text-left text-sm outline-none transition-colors duration-150 hover:bg-zinc-100 focus-visible:bg-zinc-100 dark:focus-visible:bg-zinc-900 dark:hover:bg-zinc-900"
onClick={() => moveTo(collection.id)}
type="button"
>
<span
className={cn("size-7 shrink-0 rounded-lg", collection.color)}
/>
<span className="min-w-0 flex-1">
<span className="block truncate text-zinc-900 dark:text-zinc-100">
{collection.name}
</span>
<span className="block text-[11px] text-zinc-400 tabular-nums dark:text-zinc-500">
{countFor(collection)} saved
</span>
</span>
{active && (
<Check
aria-hidden
className="size-4 text-zinc-900 dark:text-zinc-100"
strokeWidth={2.5}
/>
)}
</button>
</li>
);
})}
</ul>
<form
className="mt-1 flex h-11 items-center gap-2.5 rounded-xl border-zinc-100 border-t px-2 pt-1 dark:border-zinc-900"
onSubmit={create}
>
<span className="flex size-7 shrink-0 items-center justify-center rounded-lg border border-zinc-300 border-dashed text-zinc-400 dark:border-zinc-700">
<Plus aria-hidden className="size-3.5" />
</span>
<input
aria-label="New collection"
className="min-w-0 flex-1 bg-transparent text-sm text-zinc-900 outline-none placeholder:text-zinc-400 dark:text-zinc-100 dark:placeholder:text-zinc-500"
onChange={(event) => setDraft(event.target.value)}
placeholder="New collection"
value={draft}
/>
<AnimatePresence initial={false}>
{draft.trim() && (
<motion.button
animate={{ opacity: 1, x: 0 }}
className="h-7 shrink-0 rounded-full bg-zinc-900 px-2.5 font-medium text-[11px] text-white dark:bg-zinc-100 dark:text-zinc-900"
exit={{ opacity: 0, x: 4 }}
initial={{ opacity: 0, x: 4 }}
transition={{ duration: 0.14, ease: EASE_OUT }}
type="submit"
>
Create
</motion.button>
)}
</AnimatePresence>
</form>
</div>
);
}