# Release Pill
> The "New" badge above your headline, made useful. Hover it and the pill grows into a small changelog with your last few releases, then folds back into the pill when you leave.
An animated React component from KeyframeUI, installed as source with the shadcn CLI. Built with React, Tailwind CSS and Motion.
- Docs and live preview: https://keyframeui.com/components/release-pill
- Tags: Badge, Hover, Changelog
- npm dependencies: motion, clsx, tailwind-merge
## Installation
Register the @keyframeui registry in `components.json` once per project:
```json
{
"registries": {
"@keyframeui": "https://keyframeui.com/r/{name}.json"
}
}
```
Then add the component. It lands in `components/ui/release-pill.tsx`, and the CLI also adds `lib/utils.ts` (the `cn` helper) and installs the npm dependencies:
```bash
npx shadcn@latest add @keyframeui/release-pill
```
Or install by URL, without registering the namespace:
```bash
npx shadcn@latest add https://keyframeui.com/r/release-pill.json
```
## Usage
The main demo shows typical usage.
### Hero Badge
An AI startup's hero with the pill above the headline. Hover it and the changelog opens over the headline; a couple of seconds after it scrolls into view it peeks at the second row once, and the version rolls from v2.3 to v2.4.
Install this demo, with the component included:
```bash
npx shadcn@latest add @keyframeui/release-pill-demo
```
```tsx title="components/release-pill-demo.tsx"
import { ReleasePill, type Release } from "@/components/ui/release-pill";
const releases: Release[] = [
{
version: "v2.4",
title: "Agents 2.0",
date: "Oct 10",
href: "#agents-2",
summary: "Agents that plan, act and check their own work.",
},
{ version: "v2.3", title: "Slack approvals", date: "Sep 26", href: "#slack-approvals" },
{ version: "v2.2", title: "SOC 2 Type II", date: "Sep 12", href: "#soc-2" },
{ version: "v2.1", title: "Scheduled runs", date: "Aug 29", href: "#scheduled-runs" },
];
export function ReleasePillDemo() {
return (
The agent that does the busywork
Hand it the weekly report, the expense chasing and the calendar tetris. It plans the steps,
does them, and checks its own work before it tells you.
);
}
```
## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `releases` (required) | `Release[]` | | The releases, newest first; the first is the latest. Each one is `{ version, title, date?, href?, summary?, label? }`. `version` is shown as written ("v2.4", "Day 3") and its digits roll from the previous release's on first view. `summary` is the line under the latest title, and `label` is a small node, like a Feature tag, shown with the release in the open card. |
| `tag` | `string` | `"New"` | The small tag at the start of the pill. |
| `changelogHref` | `string` | | Adds a "View changelog →" link at the bottom of the open card. |
| `peek` | `boolean` | `false` | About 2s after the pill first scrolls into view, open just far enough to show the second row, then close. Once per page view; a pointer cancels it. Skipped with reduced motion. |
| `cycle` | `boolean \| number` | `false` | Step the closed pill through the latest releases every 4s, each title sliding up as the next arrives. A number sets how many releases; `true` is 3. A pointer or focus stops it, and opening brings the latest back. |
| `align` | `"center" \| "start"` | `"center"` | Where the card grows from: out of the pill's middle (above a centered headline) or out of its left edge. |
| `children` | `React.ReactNode` | | An extra row at the end of the list, after the releases: an upgrade command, a locked next release. |
| `className` | `string` | | Extra classes for the wrapper. Set the open card's width with `[--release-pill-width:26rem]` (default `22rem`). |
## Source
```tsx title="components/ui/release-pill.tsx"
"use client";
import * as React from "react";
import {
AnimatePresence,
animate,
motion,
useInView,
useMotionValue,
useReducedMotion,
useTransform,
} from "motion/react";
import { cn } from "@/lib/utils";
/* ─────────────────────────────────────────────────────────
* RELEASE PILL STORYBOARD
*
* rest a pill: a small tag, the latest release's title, an
* arrow and a dot that breathes
* view the first time it scrolls into view the version rolls
* digit by digit, from the previous release to the latest
* (v2.3 → v2.4), the rightmost digit first
* intent the pointer rests on it for ~120ms and it opens; sweeping
* across does nothing. Leaving waits ~250ms before it folds
* grow one shape on one spring (~0.35s, the smallest overshoot):
* width, height and corners ease from the pill to a card
* that floats over what's below, so nothing is pushed down.
* The header row stays put: its arrow and dot give way to
* the date, and the summary opens under it
* rows the rows slide out from under the one above, 40ms apart,
* each rising from 0.96 scale. Closing tucks them back in
* reverse, last row first, as the card shrinks to the pill
* peek with peek, ~2s after it first shows it opens just far
* enough to reveal the second row, holds, and closes. Once
* per page view, and a pointer cancels it
* cycle with cycle, the closed pill steps through the latest few
* releases every 4s: the title slides up as the next one
* arrives and the pill's width follows. A pointer stops it,
* and opening brings the latest back
* click a click on the header toggles it; a click on a pill the
* pointer already opened pins it, so it stays open when the
* pointer leaves. A tap toggles
* keys Enter and Space toggle, Tab walks the rows, Esc closes and
* returns focus to the pill, and tabbing out folds it
* reduced no growing, sliding or rolling: the pill resizes at once
* and the rows fade in and out
* ───────────────────────────────────────────────────────── */
const PILL = {
height: 36, // px; the closed pill
radius: 16, // px; the open card's corners (a 36px pill starts fully round, at 18)
grow: { type: "spring", visualDuration: 0.35, bounce: 0.08 },
fold: { type: "spring", visualDuration: 0.3, bounce: 0 },
row: { type: "spring", visualDuration: 0.32, bounce: 0.06 },
slot: { type: "spring", visualDuration: 0.4, bounce: 0 }, // the title's slot following a cycle
slide: { duration: 0.4, ease: [0.22, 1, 0.36, 1] }, // a cycled title sliding up
roll: { type: "spring", visualDuration: 0.7, bounce: 0.05 }, // a digit's wheel
fade: { duration: 0.15, ease: "easeOut" },
breathe: 3.2, // s per breath of the dot
intent: 120, // ms the pointer rests on the pill before it opens
leave: 250, // ms outside before it folds
stagger: 0.04, // s between rows as they slide out
tuck: 0.025, // s between rows as they tuck back in, last first
lead: 0.05, // s the shape leads the first row by
rise: 10, // px a hidden row sits above its place
scale: 0.96, // scale a hidden row starts from
cycle: 4000, // ms each release stays in a cycling pill
cycleCount: 3, // releases a cycling pill steps through
peekAfter: 2000, // ms after it first shows before a peek
peekHold: 1100, // ms a peek stays open
peekMargin: 8, // px below the second row a peek shows
rollDelay: 0.3, // s after it shows before the version rolls
rollStagger: 0.07, // s between neighboring digits
} as const;
type Phase = "closed" | "peek" | "open";
export interface Release {
/** Shown in monospace before the title, like "v2.4" or "Day 3". Digits roll from the previous release's version. */
version: string;
title: string;
/** Shown at the end of the row, like "Oct 10". */
date?: string;
/** Where the release's row links to. */
href?: string;
/** One line under the latest release's title when the pill is open. */
summary?: string;
/** Anything small shown with the release in the open card: a Feature or Fix tag. */
label?: React.ReactNode;
}
export interface ReleasePillProps extends Omit, "children"> {
/** The releases, newest first. The first one is the latest. */
releases: Release[];
/** The small tag at the start of the pill. */
tag?: string;
/** Adds a "View changelog →" link at the bottom of the open card. */
changelogHref?: string;
/** Open just far enough to show the second row, once, about 2s after the pill first shows. */
peek?: boolean;
/** Step the closed pill through the latest releases every 4s. A number sets how many; true is 3. */
cycle?: boolean | number;
/** Where the card grows from: out of the pill's middle, or out of its left edge. */
align?: "center" | "start";
/** An extra row at the end of the list, after the releases. */
children?: React.ReactNode;
}
const isDigit = (char: string) => char.length === 1 && char >= "0" && char <= "9";
/* ── VersionRoll ────────────────────────────────────────── */
// Each changing character sits in a one-character window on a short strip. A digit's strip
// counts up to its new value (3 → 4, or 4 → 0 the long way round); anything else swaps.
function VersionRoll({
from,
to,
go,
reduced,
}: {
from: string;
to: string;
go: boolean;
reduced: boolean;
}) {
const length = Math.max(from.length, to.length);
const at = (text: string, i: number) => text[i - (length - text.length)] ?? "";
const cells = Array.from({ length }, (_, i) => ({ prev: at(from, i), next: at(to, i) }));
const delays: number[] = [];
let order = 0;
for (let i = length - 1; i >= 0; i--) {
if (cells[i].prev !== cells[i].next) delays[i] = PILL.rollDelay + order++ * PILL.rollStagger;
}
const width = (char: string) => (char ? "1ch" : "0ch");
return (
<>
{to}
{cells.map(({ prev, next }, i) => {
if (prev === next) return {next};
const strip =
isDigit(prev) && isDigit(next)
? Array.from({ length: ((Number(next) - Number(prev) + 10) % 10) + 1 }, (_, k) =>
String((Number(prev) + k) % 10),
)
: [prev, next];
const transition = reduced ? { duration: 0 } : { ...PILL.roll, delay: delays[i] };
return (
{strip.map((char, k) => (
{char}
))}
);
})}
);
}
/* ── Row ────────────────────────────────────────────────── */
// One row of the list. It slides out from under the row above (which sits higher in the
// stack), and tucks back in last row first.
function Row({
index,
count,
phase,
reduced,
className,
children,
}: {
index: number;
count: number;
phase: Phase;
reduced: boolean;
className?: string;
children: React.ReactNode;
}) {
const shown = phase === "open" || (phase === "peek" && index < 2);
const delay = shown ? PILL.lead + index * PILL.stagger : (count - 1 - index) * PILL.tuck;
// Reduced motion fades; the scale and rise wait until the row has faded out.
const transition = reduced
? { default: { duration: 0, delay: shown ? 0 : PILL.fade.duration }, opacity: PILL.fade }
: {
default: { ...(shown ? PILL.row : PILL.fold), delay },
opacity: { duration: 0.2, delay },
};
return (
{children}
);
}
/* ── Face ───────────────────────────────────────────────── */
// The closed pill's contents: tag, a slot for the release, arrow, dot. It's drawn twice, once
// invisibly in the flow to give the pill its size, and once in the shape.
function Face({
tag,
slotRef,
slotStyle,
trailingStyle,
reduced,
children,
}: {
tag: string;
slotRef?: React.Ref;
slotStyle?: React.ComponentProps["style"];
trailingStyle?: React.ComponentProps["style"];
reduced: boolean;
children: React.ReactNode;
}) {
return (
{tag}
{children}
→
);
}
/* ── ReleasePill ────────────────────────────────────────── */
/**
* The "New" badge above a headline, made useful. Hover it and the pill grows into a small
* changelog with the latest releases; leave and it folds back into the pill.
*/
export function ReleasePill({
releases,
tag = "New",
changelogHref,
peek = false,
cycle = false,
align = "center",
className,
children,
onPointerEnter,
onPointerLeave,
onPointerDown,
onFocus,
onBlur,
onKeyDown,
...props
}: ReleasePillProps) {
const H: number = PILL.height;
const reduced = useReducedMotion() ?? false;
const id = React.useId();
const listId = `${id}-releases`;
const latest = releases[0];
const previous = releases.slice(1);
const cycleCount = cycle
? Math.min(releases.length, typeof cycle === "number" ? Math.max(1, cycle) : PILL.cycleCount)
: 1;
const [phase, setPhase] = React.useState("closed");
const [index, setIndex] = React.useState(0);
const [inside, setInside] = React.useState(false);
const [focused, setFocused] = React.useState(false);
const rootRef = React.useRef(null);
const sizerRef = React.useRef(null);
const ghostSlotRef = React.useRef(null);
const listRef = React.useRef(null);
const triggerRef = React.useRef(null);
const inView = useInView(rootRef, { once: true, amount: 0.6 });
// Everything that moves is a motion value, so a frame costs no React render.
const grow = useMotionValue(0); // 0 pill, 1 card: width, corners, the look
const reveal = useMotionValue(0); // 0 pill, 1 card: height
const lineWidth = useMotionValue(0); // the width of the release now in the pill
const width = useMotionValue("max-content");
const slotWidth = useMotionValue("auto");
const height = useMotionValue(H);
const radius = useMotionValue(H / 2);
const trailing = useTransform(grow, [0, 0.35], [1, 0]);
const detail = useTransform(grow, [0.4, 0.9], [0, 1]);
const tint = useTransform(grow, [0, 1], [1, 0]);
const sizes = React.useRef({
ready: false,
chrome: 0,
lines: [] as number[],
cardW: 0,
cardH: H,
peekH: H,
});
const live = React.useRef({
inside: false,
focus: false,
pinned: false,
kind: "mouse",
intent: 0,
leave: 0,
peek: 0,
peeked: false,
});
const latestState = React.useRef({ phase, index });
React.useLayoutEffect(() => {
latestState.current = { phase, index };
});
// The shape's size from its three progress values.
const sync = React.useCallback(() => {
const s = sizes.current;
if (!s.ready) return;
const g = grow.get();
const closed = s.chrome + lineWidth.get();
slotWidth.set(lineWidth.get());
width.set(closed + (s.cardW - closed) * g);
height.set(H + (s.cardH - H) * reveal.get());
radius.set(Math.max(0, H / 2 + (PILL.radius - H / 2) * g));
}, [H, grow, reveal, lineWidth, slotWidth, width, height, radius]);
const measure = React.useCallback(() => {
const sizer = sizerRef.current;
const slot = ghostSlotRef.current;
const list = listRef.current;
if (!sizer || !slot || !list) return;
const s = sizes.current;
s.chrome = sizer.getBoundingClientRect().width - slot.getBoundingClientRect().width;
s.lines = Array.from(slot.children, (line) => line.getBoundingClientRect().width);
s.cardW = list.offsetWidth;
s.cardH = H + list.offsetHeight;
const second = list.children[Math.min(1, list.children.length - 1)] as HTMLElement | undefined;
s.peekH = second
? Math.min(s.cardH, H + second.offsetTop + second.offsetHeight + PILL.peekMargin)
: s.cardH;
s.ready = true;
lineWidth.set(s.lines[latestState.current.index] ?? s.lines[0] ?? 0);
sync();
}, [H, lineWidth, sync]);
React.useLayoutEffect(() => {
measure();
const observer = new ResizeObserver(measure);
if (sizerRef.current) observer.observe(sizerRef.current);
if (listRef.current) observer.observe(listRef.current);
return () => observer.disconnect();
}, [measure]);
React.useEffect(() => {
const stops = [grow, reveal, lineWidth].map((value) => value.on("change", sync));
return () => stops.forEach((stop) => stop());
}, [grow, reveal, lineWidth, sync]);
/* Open, peek, close. */
React.useEffect(() => {
const s = sizes.current;
const open = phase !== "closed";
const target =
phase === "open"
? 1
: phase === "peek"
? Math.min(1, (s.peekH - H) / Math.max(1, s.cardH - H))
: 0;
if (reduced) {
grow.jump(open ? 1 : 0);
reveal.jump(target);
return;
}
const controls = [
animate(grow, open ? 1 : 0, open ? PILL.grow : { ...PILL.fold, delay: 0.04 }),
animate(reveal, target, open ? PILL.grow : PILL.fold),
];
return () => controls.forEach((control) => control.stop());
}, [phase, reduced, H, grow, reveal]);
/* The pill's width follows the release now showing. */
React.useEffect(() => {
const s = sizes.current;
const w = s.lines[index];
if (!s.ready || w === undefined) return;
if (reduced) {
lineWidth.jump(w);
return;
}
const control = animate(lineWidth, w, PILL.slot);
return () => control.stop();
}, [index, reduced, lineWidth]);
const clearTimers = React.useCallback(() => {
const L = live.current;
window.clearTimeout(L.intent);
window.clearTimeout(L.leave);
window.clearTimeout(L.peek);
}, []);
React.useEffect(() => clearTimers, [clearTimers]);
const openNow = React.useCallback(() => {
clearTimers();
live.current.peeked = true;
setIndex(0); // a cycling pill returns to the latest release as it opens
setPhase("open");
}, [clearTimers]);
const closeNow = React.useCallback(() => {
clearTimers();
live.current.pinned = false;
setPhase("closed");
}, [clearTimers]);
const scheduleClose = React.useCallback(() => {
const L = live.current;
window.clearTimeout(L.leave);
L.leave = window.setTimeout(() => {
if (!L.inside && !L.focus) closeNow();
}, PILL.leave);
}, [closeNow]);
/* Pointer: hover intent for mice. Taps and clicks go through the header. */
const handlePointerEnter = (event: React.PointerEvent) => {
onPointerEnter?.(event);
if (event.pointerType !== "mouse") return;
const L = live.current;
L.inside = true;
L.peeked = true; // a pointer has found it; the hint is no longer needed
setInside(true);
window.clearTimeout(L.leave);
window.clearTimeout(L.peek);
if (latestState.current.phase !== "open") {
window.clearTimeout(L.intent);
L.intent = window.setTimeout(openNow, PILL.intent);
}
};
const handlePointerLeave = (event: React.PointerEvent) => {
onPointerLeave?.(event);
if (event.pointerType !== "mouse") return;
const L = live.current;
L.inside = false;
setInside(false);
window.clearTimeout(L.intent);
if (latestState.current.phase === "open" && !L.pinned) scheduleClose();
};
const onTriggerClick = (event: React.MouseEvent) => {
const L = live.current;
const byMouse = event.detail > 0 && L.kind === "mouse";
if (latestState.current.phase !== "open") {
openNow();
L.pinned = true;
} else if (byMouse && !L.pinned) {
L.pinned = true; // the pointer opened it; a click keeps it open
} else {
closeNow();
}
};
// A click or tap outside folds it, pinned or not.
React.useEffect(() => {
if (phase !== "open") return;
const onDown = (event: PointerEvent) => {
if (!rootRef.current?.contains(event.target as Node)) closeNow();
};
document.addEventListener("pointerdown", onDown);
return () => document.removeEventListener("pointerdown", onDown);
}, [phase, closeNow]);
/* Peek: once, a couple of seconds after it first shows. */
React.useEffect(() => {
if (!peek || !inView || reduced) return;
const L = live.current;
if (L.peeked) return;
const start = window.setTimeout(() => {
if (L.peeked || latestState.current.phase !== "closed" || L.inside || L.focus) return;
L.peeked = true;
setPhase("peek");
L.peek = window.setTimeout(
() => setPhase((current) => (current === "peek" ? "closed" : current)),
PILL.peekHold,
);
}, PILL.peekAfter);
return () => window.clearTimeout(start);
}, [peek, inView, reduced]);
/* Cycle: step through the latest releases until a pointer or focus arrives. */
const engaged = inside || focused || phase !== "closed";
React.useEffect(() => {
if (cycleCount < 2 || !inView || engaged) return;
const timer = window.setTimeout(() => setIndex((i) => (i + 1) % cycleCount), PILL.cycle);
return () => window.clearTimeout(timer);
}, [cycleCount, inView, engaged, index]);
if (!latest) return null;
const current = releases[Math.min(index, releases.length - 1)];
const rollFrom = previous[0]?.version;
const rolling = index === 0 && rollFrom !== undefined && rollFrom !== latest.version;
const open = phase === "open";
const rowCount = 1 + previous.length + (children ? 1 : 0) + (changelogHref ? 1 : 0);
// A release in the pill. Only the live copy of the latest release rolls its version.
const line = (release: Release, roll = false) => (
{roll && release === latest && rolling ? (
) : (
release.version
)}
{release.title}
);
const pillAnchor = align === "center" ? "left-1/2 -translate-x-1/2" : "left-0";
const shapeStyle = { width, height, borderRadius: radius };
return (
{
onPointerDown?.(event);
live.current.kind = event.pointerType;
}}
onFocus={(event) => {
onFocus?.(event);
if (event.target.matches(":focus-visible")) {
live.current.focus = true;
setFocused(true);
}
}}
onBlur={(event) => {
onBlur?.(event);
if (event.currentTarget.contains(event.relatedTarget as Node | null)) return;
live.current.focus = false;
setFocused(false);
if (latestState.current.phase === "open") scheduleClose();
}}
onKeyDown={(event) => {
onKeyDown?.(event);
if (event.key !== "Escape" || latestState.current.phase === "closed") return;
event.preventDefault();
closeNow();
triggerRef.current?.focus();
}}
>
{/* Gives the pill its place in the page. The widest release sets its width, so a cycling pill never reflows what's beside it. */}
{releases.slice(0, cycleCount).map((release, i) => (
{line(release)}
))}