@neynar/ai-elements
Version:
React UI component library built on vercel/ai-elements, shadcn/ui and Tailwind CSS
196 lines (145 loc) • 7.22 kB
Markdown
# @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**