Getting started
Introduction
VibeUI is a library of 178 React and Tailwind components that you copy into your project. There is no runtime package: once a file is in your repo, it is yours to read, change and keep.
The copy-owned model
If you have used shadcn/ui, this will feel familiar, and that is deliberate. Instead of importing from node_modules, you add a component to src/components/ui and import it from there. Because the source is local, you can change a radius, swap an animation or delete a prop without waiting on a release, and your bundler only ever sees the code you actually use.
npx @agents-npm-packages/vibeui add dialog button --dir ./src/components/uiThat writes dialog.tsx and button.tsx and nothing else. There is no provider to mount (except ToastProvider if you use toasts), no config file and no theme object.
Design principles
- Tokens, not themes. One CSS file defines colors, radii, shadows, easing, keyframes and the dark variant. Components only read tokens, so retinting is a CSS edit.
- Ink is primary, accent is meaning. Primary actions are ink. The accent marks focus, selection, progress and live state. Pastels are for status only.
- Motion is part of the component. Hover, press, enter and exit are built in, using only transform and opacity, and they respect
prefers-reduced-motion. - Native first. Checkboxes, radios, selects and sliders are real form controls. Custom behavior is added on top, not instead.
- Four peers.
clsx,tailwind-merge,class-variance-authorityand@phosphor-icons/react. No animation library, no headless-UI dependency.
What is in the box
| Shelf | Contents |
|---|---|
| Actions | Button, Pill, Chip, Toggle, Kbd, Separator |
| Forms | Input, Select, Checkbox, Radio, Switch, Slider, Search, Password, Number, OTP, Tag input, File drop, Calendar, Rating |
| Feedback | Alert, Banner, Callout, Empty, Meter, Notification, Progress, Skeleton, Spinner |
| Data & surfaces | Card, Table, List, Avatar, Stat, Code block, Color swatch, Comparison, Scroll area, Aspect ratio |
| Overlays | Dialog, Sheet, Popover, Dropdown menu, Command, Toast, Tooltip |
| Navigation | Tabs, Segmented, Accordion, Breadcrumb, Pagination, Stepper, Timeline |
| Signature | 3D carousel, Dock, Trading card, Circle menu, Book flip, Folder preview, Spotlight, Marquee and more |
| Text effects | Typewriter, Scramble, Decode, Rolling text, Text reveal, Stagger words and more |
| Hover effects | Lift, Border, Shine, Tilt, Slide, Expand, Magnetic link and button |
| Footers | Simple, Mega, CTA, Newsletter, Legal, Social links |
Requirements
| Need | Version | Notes |
|---|---|---|
| React | 18 or newer | Components use hooks, useSyncExternalStore and useId. |
| Tailwind CSS | v4 | The token file uses @theme and @custom-variant, which are v4 syntax. |
| TypeScript | 5.x (optional) | Components are TSX. Plain JS projects can strip the types. |
| Path alias | @/* → src/* | Components import @/lib/utils. |
How it compares
VibeUI follows the same philosophy as shadcn/ui and borrows its everyday API conventions (compound components such as Card/CardHeader, cva variants and a cn() helper). It differs in a few ways that matter day to day:
| VibeUI | Typical headless-based kits | |
|---|---|---|
| Behavior layer | Written in each file, native inputs where possible | A headless primitives package |
| Motion | Built in: hover, press, enter, exit | Usually added per project |
| Tokens | One CSS file incl. keyframes and dark variant | Variables plus a Tailwind config |
| Extras | Signature pieces, text and hover effects, footers | Mostly primitives |
| Tooling | CLI, MCP server, registry JSON, llms.txt | CLI |
The trade-off is real: without a headless primitives package, complex widgets such as a fully virtualized combobox are your responsibility. See Accessibility for exactly what is and is not covered.
Where to next
Just want to look around?
Browse the live component gallery, or read the source on GitHub.