Registry

What is the Registry?

The Creative Tim UI registry is a centralized catalog system that enables CLI-based component installation based on shadcn/ui. Unlike traditional npm packages where components are locked in external dependencies, our registry delivers components as source code directly into your project.

How the Registry Works

When you run the installation command, the CLI:

1. Fetches Component Metadata: Retrieves the component definition from our registry endpoint
2. Downloads Dependencies: Identifies and installs required npm packages
3. Copies Source Files: Places component files directly into your codebase
4. Manages Imports: Automatically configures path aliases and imports

Registry Structure

Each component in the registry includes:

• Component Source Code: The actual React component files
• Type Definitions: Full TypeScript support with strict types
• Dependencies: List of required npm packages (Radix UI, etc.)
• Files Metadata: Information about where files should be placed
• Registry Dependencies: Other registry components it depends on

Installation Endpoints

Components are available through JSON endpoints:

Copy# Base UI Components
/r/button.json
/r/card.json
/r/avatar.json
 
# Custom Blocks
/r/testimonials-09.json

These endpoints return structured JSON that the CLI uses to install components.

Registry vs NPM

Registry Components

The Creative Tim UI registry currently includes:

• 47 Base UI Components: All shadcn/ui components (button, card, avatar, etc.)
• 100+ Custom Blocks: Pre-built sections like testimonials, forms, and more
• Full TypeScript Support: Type-safe component definitions
• Dark Mode Ready: Built-in theme support with CSS variables

Premium Components

The registry supports premium components with API key authentication for PRO features:

• Access control via Bearer tokens or API keys
• Gated installation for premium components
• Environment variable support for CI/CD workflows

Authentication Setup

Premium components require authentication. There are three ways to authenticate:

1. Environment Variable

Copy# Set the API key as an environment variable
export CREATIVE_TIM_UI_API_KEY=pk_live_your_key
 
# Install premium components
npx @creative-tim/ui@latest add testimonials-06

2. Config File with Environment Variable

Add to your components.json:

Copy{
  "registries": {
    "@creative-tim": {
      "url": "https://www.creative-tim.com/ui/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${CREATIVE_TIM_UI_API_KEY}"
      }
    }
  }
}

The CLI will automatically expand ${CREATIVE_TIM_UI_API_KEY} from your environment variables.

3. Command Flag

pnpmnpmyarnbun
pnpm dlx @creative-tim/ui@latest add testimonials-06 --api-key pk_live_your_key
Copy

How It Works

When you request a premium component:

1. CLI reads authentication config from components.json or command flags
2. Expands environment variables in header values (e.g., ${CREATIVE_TIM_UI_API_KEY})
3. Sends authenticated request to the registry endpoint
4. Registry validates your API key and subscription status
5. Returns component if authentication succeeds
6. Returns 401/403 if authentication fails

Error Responses

Getting Your API Key

1. Get a Creative Tim UI License
2. Visit your Creative Tim Dashboard
3. Navigate to the API Keys section
4. Copy your API key (starts with pk_live_)

Best Practices

1. Install Only What You Need: Each component is standalone, no bloat
2. Customize After Install: Treat installed components as your own code
3. Version Control: Commit installed components to your repository
4. Update Selectively: Re-run install commands to update specific components