Status chips
What the Beta and New chips in the sidebar mean, and when each one goes away.
Some sidebar entries wear a Beta or New chip, and this page tells you how far to trust an item
before you install it and when its chip ends. The chip comes from registry.json, the same file
shadcn add reads, so the docs cannot claim a stability the registry did not state.
| Chip | Means | Ends when |
|---|---|---|
| Beta | The public surface can still move, so expect props to change and read the diff when you add the item again. | Someone judges it stable. It does not time out. |
| New | Stable, and landed recently, so it is safe to depend on. | 45 days after it was stamped. |
| (none) | Stable, and has been for a while. | Not applicable. |
Where it lives
Two keys under an item's meta, which shadcn's registry schema keeps free-form:
{
"name": "pagination",
"type": "registry:ui",
"title": "Pagination",
"meta": { "status": "new", "statusSince": "2026-09-14" }
}A page names the items it documents in its frontmatter, and the first one is its own. The
Pagination page carries items: [pagination] and wears that item's chip. A page about a slice of
another item names that item, so Chip names [badge] because Chip ships inside @gesso/badge.
pnpm docs:check keeps this join honest. It fails the build when an item has no page, when a
page names an item that does not exist, or when a component page names none.
How a chip ends
The sidebar derives the chip from those two facts on every build and does not store whether one
should render. A new item therefore stops showing a chip when its window passes, whether or not
anyone edited the JSON, and the worst a stale line in registry.json can do is sit there.
Beta works the other way on purpose. Time does not make an API stable, so a beta chip never
expires on its own, and an unmaintained beta keeps warning you. What ages is its eligibility for
review. After 90 days it lands on the list that pnpm status:check prints, and a person decides.
Going stable promotes it to New with a fresh stamp, because that is news for anyone who skipped
the beta.
Maintaining the chips
These commands are for people who change the registry.
pnpm status:check # what needs attention; exits non-zero if anything does
pnpm status:prune # drop the lapsed "new" blocks
pnpm status:set <item> beta # beta | new | stable, stamped today
pnpm status:promote <item> # beta -> new, stamped todaystatus:check only reads, so it can run in CI. The windows live in lib/registry-status.ts,
which the script and the site both import, so the two cannot disagree about a date.
Deciding whether a component's surface has settled is not scriptable. That review is the
registry-status skill in .claude/skills/registry-status, and it is meant to run on the betas
that the check flags.
Next
See what changed and when in the changelog, or browse the components and check which ones are still settling.