VibeUI is a component library you copy into your project instead of installing. Add a file and it is yours to read, change and keep: no runtime package, no theme provider, no black box. Every component reads one token file, so pieces from different corners of the library look like they were made together.
Run the repo to browse all 178 components live (/components), read the docs (/docs), and open any component for its source, install command and generated API table.
Why
- You own the code. Components are single files. Re-add one to update it, or edit it freely.
- One token file. Colors, radii, shadows, easing, keyframes and the dark variant live in
templates/vibeui.css. Copied components animate and theme correctly in your app.
- Real dark mode. A
dark class on <html>, no flash, and light / dark can pin any subtree.
- Motion built in. Hover, press, focus, enter and exit on every component, using only transform and opacity, and honouring
prefers-reduced-motion.
- Native first. Checkbox, Radio, Select and Slider are real form controls, with roles and keyboard handling on the rest. See the accessibility notes, including the known gaps.
- Four peers.
clsx, tailwind-merge, class-variance-authority, @phosphor-icons/react. No animation library.
- Agent-ready. A CLI, an MCP server,
llms.txt and a JSON registry with generated API tables.
Status. Pre-1.0. Install the CLI with npx @agents-npm-packages/vibeui (see CLI). Live site: tryjasmine.dev.
Quick start
Look around locally
git clone https://github.com/arjunkshah12345-hash/vibeui.git
cd vibeui
npm install
npm run dev
| Route | What |
|---|
/ | Landing page: a live composed interface, the ten shelves with real previews, a token playground |
/components | Searchable gallery of live previews |
/components/<name> | One component: preview, install, API, source |
/docs | Installation, theming, dark mode, motion, accessibility, recipes, CLI, MCP, FAQ |
Add ?theme=dark (or light) to any URL to preview a theme.
Use it in your app
1. Install the peers
npm i clsx tailwind-merge class-variance-authority @phosphor-icons/react
2. Add the tokens and cn()
npx @agents-npm-packages/vibeui init --dir .
This writes vibeui.tokens.css and src/lib/utils.ts. Import the tokens after Tailwind:
@import "tailwindcss";
@import "../../vibeui.tokens.css";
3. Add a component
npx @agents-npm-packages/vibeui add button dialog --dir ./src/components/ui
Components that import siblings bring them along, so add footer-cta also copies button (and button copies spinner).
import { Button } from "@/components/ui/button"
<Button variant="accent" loading={saving}>Save changes</Button>
You need a @/* → src/* path alias and Tailwind CSS v4. Toasts need ToastProvider once near your root; everything else is self-contained. Vite and Next.js setup details are in /docs/installation.
Components
| Shelf | Count | Components |
|---|
| Actions | 9 | button · chip · copy-button · kbd · pill · separator · split-button · status-button · toggle |
| Forms | 17 | autosize-textarea · calendar · checkbox · combobox · file-drop · input · number-field · otp-field · password-field · radio · range-slider · rating · search-field · select · slider · switch · tag-input |
| Feedback | 12 | alert · banner · callout · empty · gauge · meter · notification · progress-ring · progress · skeleton · spinner · status-icon |
| Data & surfaces | 17 | area-chart · aspect-ratio · avatar · bar-chart · card · code-block · color-swatch · comparison · donut-chart · heatmap · list · resizable · scroll-area · sortable-list · sparkline · stat · table |
| Overlays | 11 | command · context-menu · dialog · drawer · dropdown-menu · lightbox · popover · sheet · toast · tooltip · tour |
| Navigation | 10 | accordion · breadcrumb · floating-nav · pagination · · · · · · |
Every component has hover, press and focus feedback, and anything that appears also animates out. Each page in /components lists the props (generated from the real TypeScript types), the peers it needs and the sibling components it imports.
Theming
Everything is a CSS variable. Retint the accent for both themes:
:root { --accent: #2563eb; --accent-ink: #fff; --accent-soft: rgb(37 99 235 / .1); --ring: rgb(37 99 235 / .28); }
.dark { --accent: #7aa7ff; --accent-ink: #06142e; --accent-soft: rgb(122 167 255 / .14); --ring: rgb(122 167 255 / .3); }
Both modes are monochrome by default: the accent is the ink, and one --accent variable retints everything. Radii, shadows, fonts and motion are tokens too, and you can override any of them on a single element to scope a theme. See /docs/theming, /docs/dark-mode and /docs/motion.
CLI
npx @agents-npm-packages/vibeui list --category forms
npx @agents-npm-packages/vibeui search "date picker" --json
npx @agents-npm-packages/vibeui get calendar --source
npx @agents-npm-packages/vibeui add calendar --dir ./src/components/ui
| Command | Purpose |
|---|
list, search, get | Read the registry (add --json for scripts) |
add <name…> | Copy components and the siblings they import |
init | Write the token file, utils.ts and a short guide |
categories, registry, guide, mcp | Catalog, regenerate, install guide, start the MCP server |
add exits non-zero if anything fails, so it is safe in scripts. Inside a clone, the binary is node bin/vibeui.mjs (or npm run vibeui). Full reference: /docs/cli.
Agents
Coding agents can discover and install components without scraping the site.
claude mcp add vibeui -- node /absolute/path/to/vibeui/mcp/server.mjs
Tools: search_components, get_component (source + API), add_component, get_tokens, get_utils, get_install_guide, and more. See /docs/agents and .cursor/mcp.vibeui.example.json.
Accessibility
Native controls where they exist, real roles and keyboard handling on the rest, visible focus, and reduced-motion support. It has not had a formal audit. Known gaps (for example Sheet and Popover do not trap focus, and Segmented and Rating are not arrow-key navigable) are listed honestly in /docs/accessibility.
Project layout
src/components/ui/ the library: one file per component
src/components/showcase/ demos and the gallery
src/app/ the Next.js site (landing, /components, /docs)
templates/vibeui.css the token file, single source of truth
agent/ bin/ mcp/ registry core, CLI and MCP server
scripts/ registry, API extraction, catalog, notices
registry/components.json generated catalog (committed)
Scripts
| Command | What |
|---|
npm run dev | Showcase site |
npm run build | Production build (regenerates the registry first) |
npm run check | Typecheck, lint and build |
npm run registry | Refresh the registry, API tables and this README's catalog |
npm run notices | Regenerate THIRD_PARTY_NOTICES.md |
npm run vibeui / npm run mcp | The CLI / the MCP server |
Contributing
Contributions are welcome. Read CONTRIBUTING.md for the layout, how to add a component and what a good pull request looks like, and the Code of Conduct. Report vulnerabilities privately as described in SECURITY.md. Release notes are in CHANGELOG.md.
License and credits
MIT. Third-party dependencies, fonts and icons are listed with their licenses in THIRD_PARTY_NOTICES.md.
VibeUI was inspired by shadcn/ui (the copy-owned model and its API conventions), ObsidianUI (expressive, animated craft components), Magic UI (tasteful motion) and Origin / coss ui (dense app primitives). All of those are credited for ideas, not code, and none is affiliated with this project.
