labsUI

labsui

Add labsUI components to your project: clean React primitives with one smooth spring for every motion. Components are copied into your codebase, so you own and edit them.

Requires React 19, Tailwind CSS v4 and a path alias ("paths": { "@/*": ["./src/*"] } in tsconfig.json). The CLI runs on Node.js 22 or newer, or Deno. It has no dependencies and works offline.

Usage

npx @kznlabs/labsui init                # once: styles, theme, utils, motion providernpx @kznlabs/labsui add button tabs     # components plus everything they importnpx @kznlabs/labsui search date range   # find by name, export or intentnpx @kznlabs/labsui view dialog         # props, examples, what it installsnpx @kznlabs/labsui update              # newer components, keeping your editsnpx @kznlabs/labsui doctor              # check the setup

Any runner works: bunx @kznlabs/labsui add button, pnpm dlx @kznlabs/labsui …, yarn dlx @kznlabs/labsui …, or from JSR with deno run -A jsr:@kznlabs/labsui add button. npm dependencies install with whatever package manager your lockfile shows.

The component registry ships inside the package: no network needed beyond installing npm dependencies, and each labsui version installs the same component code. npx @kznlabs/labsui@latest add … gets the newest components.

Global install

To type labsui instead of npx @kznlabs/labsui in every project:

npm install -g @kznlabs/labsui    # or: bun add -g @kznlabs/labsuideno install -gA -n labsui jsr:@kznlabs/labsui

A global install pins its components to that version, the same way the registry ships inside each release. Update it when you want newer ones (npm install -g @kznlabs/labsui@latest); npx @kznlabs/labsui@latest always gets them.

Commands

init

• Writes styles/labsui.css (tokens, accent presets, animations) and imports it right after @import "tailwindcss" in your stylesheet.
• Adds lib/utils, lib/theme and components/motion-provider, and installs motion, clsx and tailwind-merge.
• Saves labsui.json with the registry URL, your alias and its folder.
• Prints the lines your root layout needs (theme script, MotionProvider).

Run it again any time: existing files are kept.

add

Resolves dependencies through the registry (data-table brings table, checkbox, pagination, …), writes each file under your alias folder and installs the npm packages it imports. Existing files are kept unless you pass --overwrite; a kept dependency whose code differs from this version is named, with the labsui update that brings it level, since the new item may need it. If your alias isn't @/, imports are rewritten to match. Components that live once in the root layout (toast, confirm) print the line to add there. A mistyped name gets a suggestion: buton suggests button.

list and search

list shows everything: components, blocks, hooks (use-disclosure, use-hotkey, …) and helpers (utils, theme, …). Hooks and helpers come along with the components that import them; add one by name to use it on its own.

search ranks by name first, then by what an item exports, then by its description, and every word must match:

labsui search useModal         # finds dialoglabsui search toast promise    # finds toastlabsui search --kind hook      # every hooklabsui search shop             # finds the shop recipe too

It also finds recipes: a prompt for a whole app (blog, docs, shop, comparison, portfolio) that ran on a fresh app before it shipped, with the components it used. labsui view shop prints one.

view

Everything you need before writing code with an item, without leaving the terminal:

• Exact props and types of each export, read from the component source.
• A usage line and the full examples from the docs.
• What it brings along and which npm packages it installs.
• What to mount in the root layout, if anything.

Imports in the examples use your alias. --source adds the files themselves. For a recipe, view prints its prompt, its components and the patterns the result needs.

update and diff

Components are yours to edit, so an update must not silently undo your changes. labsui.json records which labsui version wrote each item, and labsui update (or labsui update dialog) uses that version as the base:

• Files you never edited are replaced.
• Edited files are merged three ways: your changes and this version's changes both land.
• Where both changed the same lines, the file gets <<<<<<< yours / >>>>>>> labsui markers and update lists it. labsui doctor fails until they are resolved.
• New dependencies of updated items are added.

The base comes from JSR, which keeps every release's files. Offline, with a hosted registry, or for items installed before versions were recorded, edited files are left as they are. labsui diff lists installed items that differ from this version and, from the same base, whose change each file is: only labsUI's (update replaces it), only yours (update keeps it) or both (update merges). It also marks files that differ only in blank lines or indentation. labsui diff dialog prints the patch from this version's file to yours, or says dialog isn't installed.

doctor

Checks the setup and prints a fix for each problem: React 19 and Tailwind v4, the path alias and labsui.json, the stylesheet import, MotionProvider and the theme script, <Toaster /> and <Confirmer /> mounted when installed, missing npm packages, and files your installed components import but the project lacks. It also lists installed items that differ from this version, your edits or an older install. Exits with 1 when something is broken, so it can run in CI.

It reads your code, not a framework's conventions: it works the same in any React app.

Coding agents

MCP server

labsui mcp serves the same commands to any agent that speaks the Model Context Protocol, over stdio. Register it with your agent:

{	"mcpServers": {		"labsui": { "command": "npx", "args": ["-y", "@kznlabs/labsui", "mcp"] }	}}

It works in the folder your agent shares as its workspace (MCP roots), or the one it starts the server in. If your agent starts servers elsewhere and shares no workspace, add "--cwd", "/path/to/app" after "mcp"; --cwd always wins. Claude Desktop is one of those: it shares no workspace, so give it --cwd. On Windows, Desktop starts npx through cmd:

{	"mcpServers": {		"labsui": {			"command": "cmd",			"args": ["/c", "npx", "-y", "@kznlabs/labsui", "mcp", "--cwd", "C:\\path\\to\\app"]		}	}}

Recipes are MCP prompts too (prompts/list), so a client that shows prompts offers them by name.

On connect, the server also sends the labsUI coding rules (imports, tokens, motion, mounting), so the agent writes code the way the library expects. It runs in the folder the agent starts it in and writes only inside that project.

Without MCP

• labsui rules prints the same coding rules as Markdown. Append them to the file your agent reads: labsui rules >> AGENTS.md.
• --json on any command prints one JSON document on stdout; npm output goes to stderr. Errors are { "error": "…" } with exit code 1.

Options

License

MIT. Every component is original, hand-made labsUI code.