---
name: kokonutui
description: This skill should be used when the user asks to "add a KokonutUI component", "use kokonutui", "install a component from kokonutui.com", or asks for polished ready-made React/Tailwind UI like AI chat inputs, animated text effects (shimmer, glitch, matrix, typewriter), gradient/particle/hold buttons, card stacks, bento grids, hero backgrounds (beams, paths), file uploads, or profile dropdowns in a Next.js/React + Tailwind project.
---

# KokonutUI

KokonutUI (kokonutui.com) is an open-source library of 40+ polished React components built with Tailwind CSS and the `motion` (Framer Motion successor) library. Components are **installed as source files into the project** via the shadcn CLI — they are not an npm package. After install, the component lives in `components/kokonutui/` and can be freely edited.

## Requirements

- React 18+/Next.js (App Router preferred) with Tailwind CSS configured
- shadcn CLI initialized in the project (`components.json` present). If not: `npx shadcn@latest init`
- Many components depend on `lucide-react` and `motion` (installed automatically by the CLI)

## Installing a component

Use the project's package runner:

```bash
npx shadcn@latest add https://kokonutui.com/r/<name>.json
# or: pnpm dlx shadcn@latest add https://kokonutui.com/r/<name>.json
# or: bunx --bun shadcn@latest add https://kokonutui.com/r/<name>.json
```

This copies the component source into `components/kokonutui/<name>.tsx`, pulls in any required hooks (e.g. `hooks/use-auto-resize-textarea.ts`), icon components, shadcn/ui primitives (button, textarea, dropdown-menu, …), and npm dependencies.

If the shared `cn()` helper is missing, install it first: `npx shadcn@latest add https://kokonutui.com/r/utils.json`.

Import after install:

```tsx
import GradientButton from "@/components/kokonutui/gradient-button";
```

## Workflow

1. **Pick the component** from `references/components.md` — the full catalog with names, descriptions, categories, and dependencies. Match on what the user is building (AI input, text effect, button, card, background, etc.).
2. **Install it** with the shadcn CLI command above — never hand-copy or re-implement a component that exists in the catalog.
3. **Read the installed source** in `components/kokonutui/<name>.tsx` to learn its actual props (props are not documented externally; the source is the contract).
4. **Customize in place.** Installed files belong to the project — edit variants, colors, and copy directly rather than wrapping.

## Key rules

- **Install before inventing.** Check the catalog first; only build custom UI when no catalog component fits.
- **Client components.** Most KokonutUI components use `motion`/hooks and carry `"use client"` — do not strip the directive; render them inside server components as children.
- **Tailwind only.** Styling is utility-class based and respects the project's dark mode (`dark:` variants are built in). Theme by editing classes, not by adding CSS overrides.
- **Check registry deps.** Components listing shadcn deps (see catalog) require those primitives; the CLI installs them, but conflicts with already-customized primitives should be resolved in favor of the project's existing versions.
- **Docs pages** live at `https://kokonutui.com/docs/components/<name>` for a visual preview; `https://kokonutui.com/llms.txt` has an LLM-oriented index.

## Component categories (40+ items)

| Category | Highlights |
|---|---|
| ai | ai-prompt (chat input with model selector), ai-input-search, ai-voice, ai-text-loading, ai-loading |
| texts | shimmer-text, glitch-text, matrix-text, type-writer, sliced-text, swoosh-text, dynamic-text, scroll-text |
| buttons | gradient-button, particle-button, hold-button, attract-button, social-button, switch-button, command-button, v0-button |
| cards | card-flip, card-stack, apple-activity-card, liquid-glass-card, tweet-card, carousel-cards |
| backgrounds | beams-background, background-paths, shape-hero |
| components | bento-grid, file-upload, action-search-bar, smooth-tab, smooth-drawer, toolbar, team-selector, avatar-picker, profile-dropdown, currency-transfer |

Full catalog with descriptions and dependencies: **`references/components.md`**.