---

description: This is how to create a registry component globs:

Cursor Rules for Adding New UI Components to Cult UI Registry

Overview

This document outlines the complete process for adding a new UI component to the Cult UI registry system. Follow these steps in order to ensure proper integration.

Step-by-Step Process

1. Create the Component File

Location: apps/www/registry/default/ui/[component-name].tsx

Requirements:

• Use TypeScript with React
• Include proper TypeScript interfaces for props
• Use "use client" directive if component uses client-side features
• Export the component with a descriptive name (e.g., TextureButton)
• Include displayName for debugging
• Use proper imports from @/lib/utils for cn utility
• Follow existing component patterns for styling and structure

Example structure:

"use client"

import * as React from "react"
import { cva } from "class-variance-authority"

import { cn } from "@/lib/utils"

// Component variants using cva
const componentVariants = cva("base-classes", {
  variants: {
    variant: {
      default: "default-classes",
      // other variants
    },
    size: {
      default: "default-size",
      // other sizes
    },
  },
  defaultVariants: {
    variant: "default",
    size: "default",
  },
})

export interface ComponentProps extends React.HTMLAttributes<HTMLElement> {
  variant?: "default" | "other"
  size?: "default" | "other"
  // other props
}

const ComponentName = React.forwardRef<HTMLElement, ComponentProps>(
  ({ className, variant, size, ...props }, ref) => {
    return (
      <element
        className={cn(componentVariants({ variant, size }), className)}
        ref={ref}
        {...props}
      />
    )
  }
)

ComponentName.displayName = "ComponentName"

export { ComponentName }

2. Create the Example/Demo File

Location: apps/www/registry/default/example/[component-name]-demo.tsx

Requirements:

• Use "use client" directive
• Import the component from the correct path: @/registry/default/ui/[component-name]
• Create a comprehensive demo showing all variants and use cases
• Use proper styling with dark mode support
• Include responsive design considerations
• Export as default function with descriptive name

Example structure:

"use client"

import { ComponentName } from "@/registry/default/ui/component-name"

export default function ComponentNameDemo() {
  return (
    <div className="dark:bg-stone-950 py-6 px-4 md:px-0 rounded-md flex justify-center">
      <div>
        {/* Demo content showing all variants */}
        <div className="flex flex-col gap-3 max-w-lg mt-4">
          <ComponentName variant="default">Default</ComponentName>
          <ComponentName variant="other">Other Variant</ComponentName>
        </div>
      </div>
    </div>
  )
}

3. Create Documentation File

Location: apps/www/content/docs/components/[component-name].mdx

Requirements:

• Include frontmatter with title, description, and component flag
• Add ComponentPreview with the demo name
• Include installation instructions (CLI and manual)
• Provide usage examples
• Follow existing documentation patterns

Example structure:

---
title: ComponentName
description: Brief description of the component
component: true
links:
---

<ComponentPreview
  name="component-name-demo"
  className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]"
  description="All variations"
/>

## Installation

<CodeTabs>

<TabsList>
  <TabsTrigger value="cli">CLI</TabsTrigger>
  <TabsTrigger value="manual">Manual</TabsTrigger>
</TabsList>

<TabsContent value="cli">

```bash
npx shadcn@latest add https://cult-ui.com/r/component-name.json
```

</TabsContent>

<TabsContent value="manual">

<Steps>

<Step>Copy and paste the following code into your project.</Step>

<ComponentSource name="component-name" />

<Step>Update the import paths to match your project setup.</Step>

</Steps>

</TabsContent>

</CodeTabs>

## Usage



```tsx
<ComponentName variant="default">Content</ComponentName>
```

4. Update Registry Files

A. Update apps/www/registry/ui.ts

Add a new entry to the ui array:

{
  name: "component-name",
  type: "registry:ui",
  dependencies: ["dependency1", "dependency2"], // or [""] if no dependencies
  files: [
    {
      path: "registry/default/ui/component-name.tsx",
      type: "registry:ui",
    },
  ],
},

Dependencies to consider:

• framer-motion - for animations
• @radix-ui/react-slot - for polymorphic components
• react-use-measure - for measurements
• three - for 3D components
• jotai - for state management
• next/image - for Next.js image optimization
• button - for button dependencies
• aspect-ratio - for aspect ratio components

B. Update apps/www/registry/examples.ts

Add a new entry to the examples array:

{
  name: "component-name-demo",
  type: "registry:component",
  registryDependencies: ["component-name"], // include other dependencies if needed
  files: [
    {
      path: "registry/default/example/component-name-demo.tsx",
      type: "registry:component",
    },
  ],
},

5. Update Documentation Configuration

File: apps/www/config/docs.ts

Add the new component to the appropriate section in the sidebarNav array. Choose the correct category:

• Buttons & Controls: For button-like components
• Cards & Containers: For card and container components
• Onboarding & Tours: For onboarding and tutorial components
• Layout & Forms: For layout and form components
• Interactive Elements: For interactive UI elements
• Media: For media-related components
• Typography & Text: For text and typography components
• Visual Effects: For visual effect components

Example addition:

{
  title: "Component Display Name",
  href: "/docs/components/component-name",
  items: [],
  // Optional: label: "new" | "recent"
},

Naming Conventions

File Names

• Use kebab-case for file names: component-name.tsx
• Use kebab-case for demo files: component-name-demo.tsx
• Use kebab-case for documentation: component-name.mdx

Component Names

• Use PascalCase for component names: ComponentName
• Use descriptive, clear names that indicate the component's purpose

Registry Names

• Use kebab-case for registry entries: component-name
• Use kebab-case for demo registry entries: component-name-demo

Dependencies

Common Dependencies

• framer-motion - Animation library
• @radix-ui/react-slot - Polymorphic component support
• react-use-measure - Element measurement hooks
• three - 3D graphics library
• jotai - State management
• next/image - Next.js image optimization
• button - Button component dependency
• aspect-ratio - Aspect ratio component

Dependency Guidelines

• Always include framer-motion if the component has animations
• Include @radix-ui/react-slot if the component supports polymorphic rendering
• Include react-use-measure if the component needs to measure elements
• Include three and jotai for 3D components
• Include next/image if using Next.js image optimization
• Include other registry components as registryDependencies if they're used

Testing Checklist

Before considering the component complete, verify:

• Component file created in apps/www/registry/default/ui/
• Demo file created in apps/www/registry/default/example/
• Documentation file created in apps/www/content/docs/components/
• Entry added to apps/www/registry/ui.ts
• Entry added to apps/www/registry/examples.ts
• Entry added to apps/www/config/docs.ts
• Component renders correctly in all variants
• Demo shows all component variations
• Documentation is complete and accurate
• All dependencies are properly declared
• TypeScript types are correct
• Component follows existing patterns and conventions

File Structure Summary

apps/www/
├── registry/
│   ├── default/
│   │   ├── ui/
│   │   │   └── [component-name].tsx          # Component implementation
│   │   └── example/
│   │       └── [component-name]-demo.tsx     # Demo/example
│   ├── ui.ts                                 # Registry entries
│   └── examples.ts                           # Example registry entries
├── content/docs/components/
│   └── [component-name].mdx                  # Documentation
└── config/
    └── docs.ts                               # Navigation configuration

Notes

• Always follow existing patterns and conventions
• Ensure components are accessible and responsive
• Test components in both light and dark modes
• Use proper TypeScript types and interfaces
• Include comprehensive examples in demos
• Write clear, helpful documentation
• Consider the component's placement in the navigation structure