# @neynar/ui Component Library

A production-ready React component library with 265+ components, hooks, and utilities. Built on Radix UI primitives with Tailwind CSS v4, ensuring WCAG-compliant accessibility and zero runtime overhead.

## Quick Reference

```typescript
import { Button, Card, useIsMobile, cn } from "@neynar/ui"
import "@neynar/ui/styles"
```

## 🔍 How to Search Components

**IMPORTANT:** DO NOT load the entire `llm-docs/sdk-items-registry.json` file - it contains 265+ items and will exceed context limits.

Instead, search efficiently using these methods:

### Method 1: Search by Component Name (Recommended)
```bash
# Search for specific component documentation
cat llm-docs/{component-name}.llm.md
# Example: cat llm-docs/button.llm.md
```

### Method 2: Search Registry by Keywords  
```bash
# Use jq to search registry by keywords without loading entire file
jq 'to_entries[] | select(.value.keywords[]? | contains("button")) | {key: .key, description: .value.description}' llm-docs/sdk-items-registry.json
```

### Method 3: List Components by Category
Use these patterns to find components:
- **button** → Button, Toggle, ToggleGroup
- **form** → Input, Textarea, Checkbox, Select, Switch
- **navigation** → NavigationMenu, Breadcrumb, Tabs, Sidebar
- **overlay** → Dialog, Sheet, Popover, Tooltip
- **layout** → Container, Stack, Card, Accordion

## Common Mistakes and Corrections

**CRITICAL Typography Errors:**
- ❌ `<h1>`, `<p>`, `<span>` - NEVER use plain HTML elements
- ❌ `Text` component does NOT exist 
- ❌ `<div>Some text</div>` - wrap text in typography components

**CRITICAL Component Name Errors:**
- ❌ `Stack direction="col"` - use `direction="vertical"`  
- ❌ `Stack gap="4"` - use `spacing="md"`
- ❌ `Badge variant="success"` - use `variant="secondary"`

**Correct Usage:**
```typescript
import { H1, H2, P, Span, Code, Stack, Badge } from "@neynar/ui"

// ✅ Always use typography components for text
<H1>Main Title</H1>
<H2>Section Title</H2>
<P>Body text content with <Strong>emphasis</Strong></P>
<Small color="muted">Updated <Code>2024-01-15</Code></Small>

// ✅ Typography in containers
<Card>
  <CardHeader>
    <H3>Card Title</H3>
    <P color="muted">Description text</P>
  </CardHeader>
</Card>

// ✅ Stack with correct props
<Stack direction="vertical" spacing="md">
  <P>First paragraph</P>
  <P>Second paragraph</P>
</Stack>

// ✅ Badge with valid variants only
<Badge variant="default">Active</Badge>
<Badge variant="secondary">Draft</Badge>
<Badge variant="destructive">Error</Badge>
<Badge variant="outline">Pending</Badge>
```

## Registry Structure

The `llm-docs/sdk-items-registry.json` contains metadata for all components:

```json
{
  "ComponentName": {
    "description": "Brief component description with usage context",
    "file": "component-name.llm.md",
    "type": "component|hook|function|type",  
    "keywords": ["relevant", "search", "terms"]
  }
}
```

## Efficient Search Strategy

For component discovery, use this approach:

1. **Know what you need?** → Use Method 1 (direct file access)
2. **Searching by functionality?** → Use Method 2 (keyword search)  
3. **Browsing categories?** → Use Method 3 (category patterns)
4. **Need complete list?** → Use `jq 'keys' llm-docs/sdk-items-registry.json`

**Performance Tip:** Each .llm.md file contains complete documentation including props, examples, and TypeScript definitions. Only load what you need.

## Component Categories

### Layout Components → [docs/llm/components/layout.md](docs/llm/components/layout.md)
- **Container** - Responsive container with max-width constraints
- **Stack** - Flexible vertical and horizontal layout primitive  
- **Separator** - Visual content dividers
- **AspectRatio** - Responsive aspect ratio containers
- **ResizablePanelGroup**, **ResizablePanel**, **ResizableHandle** - Interactive resizable layouts
- **ScrollArea**, **ScrollBar** - Custom scrollable areas
- **Accordion**, **AccordionItem**, **AccordionTrigger**, **AccordionContent** - Collapsible sections
- **Collapsible**, **CollapsibleTrigger**, **CollapsibleContent** - Simple show/hide content

### Navigation Components → [docs/llm/components/navigation.md](docs/llm/components/navigation.md)
- **NavigationMenu** + 8 sub-components - Complex navigation menus
- **Breadcrumb** + 6 sub-components - Hierarchical navigation  
- **Pagination** + 6 sub-components - Data pagination
- **Menubar** + 14 sub-components - Desktop-style menu bars
- **Sidebar** + 20 sub-components - Application sidebars
- **Tabs**, **TabsList**, **TabsTrigger**, **TabsContent** - Tabbed interfaces

### Form Components → [docs/llm/components/forms.md](docs/llm/components/forms.md)
- **Input** - Text input fields with validation states
- **Textarea** - Multi-line text input with auto-resize
- **TextField** - Complete form field with label and validation
- **Label** - Accessible form labels
- **Checkbox** - Boolean input with indeterminate state
- **RadioGroup**, **RadioGroupItem** - Single-choice selection
- **Switch** - Toggle switch for boolean settings
- **Slider** - Range input for numeric values
- **DatePicker** - Calendar-based date selection
- **Combobox** - Searchable dropdown with custom options
- **Select** + 9 sub-components - Dropdown selection

### Button Components → [docs/llm/components/buttons.md](docs/llm/components/buttons.md)
- **Button** - Primary action component with variants and sizes
- **Toggle**, **ToggleGroup**, **ToggleGroupItem** - Multi-state buttons

### Card Components → [docs/llm/components/cards.md](docs/llm/components/cards.md)
- **Card** + 5 sub-components - Content containers

### Display Components → [docs/llm/components/display.md](docs/llm/components/display.md)
- **Badge** - Status and category indicators
- **Avatar** + 2 sub-components - User profile pictures
- **Progress** - Loading and completion indicators
- **Skeleton** - Loading state placeholders
- **Chart** + 5 sub-components - Data visualization
- **EmptyState** - No data placeholder with actions

### Table Components → [docs/llm/components/tables.md](docs/llm/components/tables.md)
- **Table** + 7 sub-components - Data tables

### Overlay Components → [docs/llm/components/overlays.md](docs/llm/components/overlays.md)
- **Dialog** + 7 sub-components - Modal dialogs
- **AlertDialog** + 8 sub-components - Confirmation dialogs
- **Sheet** + 6 sub-components - Side panel overlays
- **Drawer** + 6 sub-components - Mobile-first bottom sheets
- **Popover** + 3 sub-components - Contextual overlays
- **HoverCard** + 2 sub-components - Hover-triggered content
- **Tooltip** + 3 sub-components - Informational overlays

### Menu Components → [docs/llm/components/menus.md](docs/llm/components/menus.md)
- **DropdownMenu** + 15 sub-components - Context menus
- **ContextMenu** + 15 sub-components - Right-click menus
- **Command** + 8 sub-components - Command palette interfaces
- **Calendar** + 1 sub-component - Full calendar interface
- **Carousel** + 4 sub-components - Content slideshows

### Feedback Components → [docs/llm/components/feedback.md](docs/llm/components/feedback.md)
- **Alert** + 2 sub-components - Status messages and notifications
- **Toaster**, **toast** - Toast notification system (Sonner-based)
- **ThemeToggle** - Dark/light mode switcher

### Typography Components → [docs/llm/components/typography.md](docs/llm/components/typography.md)

**CRITICAL: Always use typography components instead of plain HTML elements**

The typography system provides semantic HTML components with consistent styling:

#### Semantic HTML Components (Use These Instead of Plain HTML)
```typescript
// ❌ DON'T use plain HTML elements
<h1>Title</h1>
<p>Content</p>
<span>Text</span>
<a href="#">Link</a>

// ✅ DO use typography components  
<H1>Title</H1>
<P>Content</P>
<Span>Text</Span>
<A href="#">Link</A>
```

#### Available Components
- **H1, H2, H3, H4, H5, H6** - Semantic headings with proper hierarchy
- **P** - Paragraph text with body variant styling
- **Span** - Inline text with default styling  
- **A** - Links with proper hover/focus states
- **Code** - Inline code with monospace styling
- **Small** - Small text for captions/metadata
- **Strong** - Bold text for emphasis
- **Lead** - Large introductory text
- **Blockquote** - Quoted content with border styling

#### Typography Pattern: Use for ALL Text Content
```typescript
// Content containers - wrap ALL text with typography components
<Card>
  <CardHeader>
    <H2>Card Title</H2>
    <P color="muted">Card description</P>
  </CardHeader>
  <CardContent>
    <P>Main content paragraph</P>
    <Small color="muted">Last updated: <Code>2024-01-15</Code></Small>
  </CardContent>
</Card>

// Form labels and descriptions
<Label>
  <Strong>Field Label</Strong>
</Label>
<Small color="muted">Field description text</Small>

// Navigation and UI text
<Button>
  <Span>Button Text</Span>
</Button>
```

#### Color Variants
- `color="default"` - Standard text color
- `color="muted"` - Subdued text for secondary info
- `color="accent"` - Emphasis and highlights
- `color="destructive"` - Error messages
- `color="success"` - Success messages

#### When to Use Each Component
- **H1-H6**: Page/section headings (semantic hierarchy)
- **P**: Body paragraphs and main content
- **Span**: Inline text within other components
- **Code**: Inline code, values, technical terms
- **Small**: Timestamps, captions, fine print
- **Strong**: Bold emphasis within text
- **Lead**: Large introductory paragraphs
- **A**: All clickable text links
- **Blockquote**: Quoted content
- **Typography**: ⚠️ Last resort only - when there's no semantic component for the type of content you want to display (semantic components already handle all styling variants)

## Utilities & Hooks → [docs/llm/components/utilities.md](docs/llm/components/utilities.md)
- **cn()** - Class name merging with Tailwind conflict resolution
- **useIsMobile()** - Responsive breakpoint detection (768px)
- **useTheme()** - Theme state management with system preference detection

## TypeScript Standards

All components follow these patterns:
- Function declarations (not const/arrow functions)
- Named exports only
- Type definitions (not interfaces)
- Comprehensive prop types
- Full IntelliSense support

```typescript
// ✅ Correct patterns
import { Button, type ButtonProps } from "@neynar/ui"

function MyButton(props: ButtonProps) {
  return <Button {...props} />
}
```

## Additional Documentation

- **[docs/llm/guide.md](docs/llm/guide.md)** - Core composition patterns and usage examples
- **[docs/llm/colors.md](docs/llm/colors.md)** - Tailwind CSS color system and design tokens

## Source Code Access
- **src/** - Complete TypeScript source with TSDoc comments, type definitions, and implementation details

## Key Features
- Built on Radix UI primitives + Tailwind CSS v4
- WCAG-compliant accessibility
- Tree-shakeable and performant
- Zero runtime overhead