registry-as-code · MIT

Components that handle the parts you always forget.

Copy-paste ownership, inspired by shadcn — extended with every state, verified accessibility, and an upgrade path that survives your edits.

Star on GitHub

5

async states, handled

AA

accessibility, verified

0

runtime dependencies

<StateBoundary/>

The problem

Copy-paste ownership changed everything. It still leaves the hard parts to you.

shadcn made copy-paste ownership the norm, and ibirdui is built on that same idea — you own every line. But owning the code still means re-implementing loading, empty and error states in every project; accessibility gets asserted, never checked; and once you edit a copied file, you can never upgrade it. ibirdui picks up where that pattern leaves off, adding the two things ownership usually costs you — completeness and maintainability.

You re-write every state

Loading skeletons, empty slots, error + retry — hand-rolled again and again, inconsistently.

Accessibility is unchecked

Roles and labels are claimed in a README, not enforced by a test that fails the build.

No upgrade path

The moment you touch the copied file, you're cut off from every future fix and improvement.

01 — State-complete by construction

Write the happy path. Get the other four states free.

Every component speaks one async contract — AsyncState<T> with five states. The loading skeleton, empty slot, error + retry, and screen-reader announcements are provided. You write one row.

idleloadingemptyerrorsuccess

<DataList label="Users" />

4 users

Ada Lovelace

Maintainer

Grace Hopper

Admin

Alan Turing

Member

Radia Perlman

Member

upgrade — zsh

02 — Upgradeable copy-paste

Upgrades that respect the edits you made.

ibirdui add writes a ibirdui.lock.json — a version and a content fingerprint per file. ibirdui upgrade updates files you haven't touched, and for files you edited it never overwrites — it drops the new version as *.new for you to merge.

Untouched files update cleanly in place.
Your edits are detected by fingerprint and never clobbered.
Conflicts land as .new so you merge on your terms.

Components

Shipped today. Production-ready.

31 components are live now — each state-complete, AA-verified and upgradeable. Each comes with a full tutorial, live example and API reference.

Browse all 36 components

async-stateShipped

The AsyncState<T> contract — the five states every component speaks.

lib

Read docs

themeShipped

Semantic CSS variables (background, foreground, primary…) with dark and light, plus the Tailwind preset.

tokens

Read docs

use-asyncShipped

Run an async function and get a typed AsyncState back, with retry built in.

hook

Read docs

use-optimistic-listShipped

Mutate a list optimistically and roll back on error.

hook

Read docs

use-onlineShipped

Reactive online/offline status — SSR-safe via useSyncExternalStore.

hook

Read docs

skeletonShipped

Decorative loading placeholder — pulses, aria-hidden, respects reduced motion.

componenta11y AA

Read docs

How it works

No backend. Just static files.

The registry is source. It builds to static JSON. The CLI copies files into your project and records a lock.

registry/items/*

Source of truth

Each component is authored once with its code, manifest, and axe test.

/r/*.json

Static registry

Builds to plain JSON on GitHub Pages — no server, no database.

your-project/

You own it

The CLI copies files in and writes ibirdui.lock.json.

Building on shadcn

The shadcn model, with the gaps filled in.

ibirdui stands on shadcn's shoulders — the same copy-paste ownership you already know, nothing relearned. Here's what it adds on top for production.

Feature comparison of ibirdui, shadcn/ui, and hand-rolled components
Capability	ibirdui	shadcn/ui	Hand-rolled
You own the code	✓	✓	✓
Loading / empty / error built-in	✓	–	–
Optimistic & offline states	✓	–	–
Verified accessibility (axe)	✓	~	–
Upgrade path for copied code	✓	–	–
AI manifest for codegen	✓	–	–

Quick start

Add your first component in seconds.

npx ibirdui list

npx ibirdui add data-list

npx ibirdui upgrade

async-state.ts

export type AsyncState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "empty" }
  | { status: "error"; error: Error; retry: () => void }
  | { status: "success"; data: T };

users.tsx

<DataList state={users} label="Users" getKey={(u) => u.id}>
  {(u) => <UserRow user={u} />}
</DataList>

Roadmap

Six layers, building up.

36 components, each layer composing the one beneath it. 31 shipped, the rest mapped out.

Components that handle the parts you always forget.

Copy-paste ownership changed everything. It still leaves the hard parts to you.

You re-write every state

Accessibility is unchecked

No upgrade path

Write the happy path. Get the other four states free.

Upgrades that respect the edits you made.

Accessibility you can verify. Components an AI can read.

Shipped today. Production-ready.

No backend. Just static files.

Source of truth

Static registry

You own it

The shadcn model, with the gaps filled in.

Add your first component in seconds.

Six layers, building up.