npm package: @neynar/ai-elements
Description: React UI component library built on vercel/ai-elements, shadcn/ui and Tailwind CSS
Author: Neynar Inc.
Latest version: 0.0.1

# @neynar/ui

A comprehensive, production-ready React component library built on **Radix UI** primitives and **Tailwind CSS v4**. Features 52 accessible components plus advanced hooks for building modern web applications with confidence.

## 🎯 Key Highlights

- **Over 50 Components, Hooks and Utilities** - Complete UI ecosystem for any application type
- **Accessibility-First** - WCAG 2.1 AA compliant with comprehensive keyboard navigation
- **TypeScript Native** - Full type safety with intelligent IntelliSense support
- **Advanced Theming** - OKLCH color space with system-aware custom themes
- **Framework Agnostic** - Seamless integration with Next.js, Vite, Remix, and more
- **Zero-Config Dark Mode** - Intelligent theme system with SSR-safe persistence
- **shadcn/ui Enhanced** - Extends shadcn/ui patterns with advanced features
- **Tree Shakeable** - Optimized bundle sizes with granular imports

## 🚀 Quick Installation

```bash
npm install @neynar/ui
# or
yarn add @neynar/ui
# or
pnpm add @neynar/ui
```

## ⚡ Get Started in 30 Seconds

```tsx
import { Button, Card, CardHeader, CardTitle, CardContent } from "@neynar/ui";
import "@neynar/ui/styles";

function App() {
  return (
    <Card className="max-w-md">
      <CardHeader>
        <CardTitle>@neynar/ui is Ready</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <Button>Primary Action</Button>
        <Button variant="outline">Secondary Action</Button>
      </CardContent>
    </Card>
  );
}
```

## 🎨 Component Categories

| Category | Components | Description |
|----------|------------|-------------|
| 📝 **Forms & Input** | Button, Input, Textarea, TextField, Select, Combobox, Checkbox, Switch, RadioGroup, DatePicker, Calendar, Label, Slider | Essential form building blocks with validation support |
| 📱 **Layout & Structure** | Container, Stack, Card, Separator, AspectRatio, Accordion, Collapsible, Resizable, ScrollArea | Flexible components for responsive layouts |
| 🧭 **Navigation & Menus** | NavigationMenu, Tabs, Breadcrumb, Pagination, Sidebar, DropdownMenu, ContextMenu, Menubar, Command | Comprehensive navigation solutions |
| 💬 **Overlays & Dialogs** | Dialog, AlertDialog, Popover, Tooltip, Sheet, HoverCard, Drawer | Modal interactions with advanced positioning |
| ✍️ **Typography** | Typography (with H1-H6, P, A, Code, Label variants) | Consistent text styling with semantic HTML |
| 📊 **Data Display** | Table, Badge, Avatar, Alert, Progress, Skeleton, EmptyState, Chart, Carousel, Sonner | Rich components for presenting information |
| 🔧 **Interactive Controls** | Toggle, ToggleGroup, ThemeToggle | Advanced interaction components |
| 🪝 **Hooks** | useTheme, useIsMobile | React hooks for common functionality |
| 🛠️ **Utilities** | cn, Theme | Helper utilities and setup components |

## 🌙 Theming

Zero-config light/dark mode with FOUC prevention:

```tsx
// 1. Add Theme component early in your app (required for FOUC prevention)
import { Theme } from "@neynar/ui";

// Next.js App Router
export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <Theme /> {/* Prevents flash of wrong theme */}
      </head>
      <body>{children}</body>
    </html>
  );
}

// Vite/React
function App() {
  return (
    <>
      <Theme /> {/* Place at the top */}
      <div className="app">
        {/* Your app content */}
      </div>
    </>
  );
}

// 2. Add ThemeToggle anywhere for user control (optional)
import { ThemeToggle } from "@neynar/ui";

function Header() {
  return (
    <header>
      <h1>My App</h1>
      <ThemeToggle />
    </header>
  );
}
```

**How it works:**

- **Theme component** - Injects a tiny script that runs before first paint
- **No FOUC** - Theme applied instantly on page load
- **Auto-detects** system preference (light/dark)
- **Persists** selection in cookies (SSR-safe)
- **Synchronized** - Multiple ThemeToggle instances stay in sync via events
- **Framework agnostic** - Works with Next.js, Vite, Remix, etc.

**[→ Complete Theming Guide](./docs/theming.md)** - Learn how to customize colors, create brand themes, and advanced theming patterns.

## 🔧 Framework Integration

@neynar/ui works seamlessly with all modern React frameworks:

- **[Next.js Integration →](./docs/integrations/nextjs.md)** - App Router, Pages Router, SSR, SSG, and custom Link components
- **[Vite + React Integration →](./docs/integrations/vite.md)** - SPA, React Router, and development setup

## 📈 Performance & Bundle Optimization

### Tree Shaking

Import only what you need for optimal bundle sizes:

```tsx
// ✅ Good - Import specific components
import { Button, Card, CardHeader, CardTitle, CardContent } from "@neynar/ui";

// ❌ Avoid - Imports entire library
import * as UI from "@neynar/ui";
```

## 📚 Documentation

### 📖 Available Documentation

- **[Component Reference](./docs/components.md)** - Complete component catalog with usage examples
- **[Troubleshooting Guide](./docs/troubleshooting.md)** - Common issues and solutions

### 🤖 AI & Development Resources

- **[LLM Documentation](./docs/llm/)** - LLM-optimized component usage and templates

## 🛡️ Quality Assurance

### Accessibility Standards

- **WCAG 2.1 AA Compliance** - All components meet accessibility standards
- **Keyboard Navigation** - Full keyboard support across all interactive elements
- **Screen Reader Support** - Comprehensive ARIA implementation
- **Focus Management** - Intelligent focus trapping and restoration
- **Color Contrast** - Meets contrast requirements in all themes

## 🤝 Contributing & Support

### Community Resources

- **[Storybook Documentation](https://neynar-ui.vercel.app)** - Interactive component explorer

### Contributing Guidelines

- **[Contributing Guide](./CONTRIBUTING.md)** - Complete guide for adding new components
- **[LLM Prompts](./docs/llm-prompts/)** - Copy-paste prompts for creating shadcn-based and custom components

This library extends shadcn/ui patterns with Neynar-specific enhancements. When contributing:

- Follow our component categorization system (Buttons, Forms, Display, etc.)
- Include comprehensive TypeScript definitions and TSDoc documentation
- Create Storybook stories with proper category organization
- Update all documentation files (AI docs, component docs, exports)
- Ensure accessibility-first implementations with full keyboard support
- Pass all automated tests including accessibility compliance checks

## 📄 License

MIT License - see the [LICENSE](./LICENSE) file for complete details.

### Acknowledgments

This library is built on top of excellent open-source projects:

- **[shadcn/ui](https://ui.shadcn.com)** - Component patterns and design system foundation (MIT)
- **[Radix UI](https://www.radix-ui.com)** - Accessible component primitives (MIT)
- **[Tailwind CSS](https://tailwindcss.com)** - Utility-first CSS framework (MIT)
- **[Lucide Icons](https://lucide.dev)** - Beautiful open-source icons (ISC)
- **[class-variance-authority](https://cva.style)** - Component variant management (Apache-2.0)

---

**Built with ❤️ by the Neynar team**