SmoothUI

SmoothUI is a collection of beautifully designed components with smooth animations built with React, Tailwind CSS, and Motion. This project aims to provide developers with a set of reusable UI components that enhance user experience through delightful animations and modern design patterns.

Table of Contents

• SmoothUI
  • Table of Contents
  • Features
  • Quick Start
  • Installation
    • Using SmoothUI CLI
    • Using shadcn CLI
    • Manual Installation
  • Usage
    • Basic Usage
    • Advanced Usage
  • Available Components
    • UI Components
    • Interactive Components
    • Layout Components
    • Utility Components
  • MCP Support
    • 🤖 AI Assistant Integration
    • Quick MCP Setup
  • Registry System
    • Automatic Dependencies
    • Component Structure
    • Registry Features
  • Troubleshooting
    • Common Issues
      • 1. Authentication Error (401)

Features

• Modern Design System: A cohesive and contemporary design language with a new mascot called Smoothy
• Smooth Animations: Built-in animations powered by Motion for delightful user experiences
• Responsive Design: Fully responsive components designed with Tailwind CSS
• Dark Mode Support: Components support both light and dark themes out of the box
• Color Customization: Dynamic color switcher for easy theme customization
• Documentation: Comprehensive documentation with props, examples, and usage guidelines
• Accessibility: Enhanced accessibility features across all components
• TypeScript Support: Full TypeScript support with type definitions
• Easy Integration: Simple API for integrating components into your projects
• CLI Tools: Dedicated SmoothUI CLI and shadcn registry support for easy component installation

Quick Start

Get started with SmoothUI in just one command:

# Using SmoothUI CLI (recommended)
npx smoothui-cli add siri-orb

# Or using shadcn CLI
npx shadcn@latest add @smoothui/siri-orb

Then use the component:

import { SiriOrb } from "@/components/smoothui/ui/SiriOrb";

export default function App() {
  return <SiriOrb size="200px" />;
}

Installation

Using SmoothUI CLI

The SmoothUI CLI provides an interactive way to browse and install components with automatic dependency resolution.

# Add a single component
npx smoothui-cli add siri-orb

# Add multiple components
npx smoothui-cli add siri-orb rich-popover animated-input

# Interactive mode - browse and select components
npx smoothui-cli add

# List all available components
npx smoothui-cli list

Features:

• Interactive component picker with search and categories
• Auto-detects package manager (npm, pnpm, yarn, bun)
• Auto-detects component paths and tsconfig aliases
• Shows dependency tree before installation
• Handles file conflicts with overwrite prompts
• Auto-installs npm dependencies

Using shadcn CLI

SmoothUI is an official shadcn registry, so you can install components directly using the @smoothui namespace:

# Install a single component
npx shadcn@latest add @smoothui/siri-orb

# Install multiple components
npx shadcn@latest add @smoothui/rich-popover @smoothui/animated-input

Manual Installation

If you prefer to install components manually, you can copy the component files directly:

1. Install dependencies:

pnpm add motion tailwindcss lucide-react clsx tailwind-merge

2. Copy component files from the components directory

3. Set up utilities:

# Create lib/utils/cn.ts
mkdir -p lib/utils

// lib/utils/cn.ts
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Usage

Basic Usage

import { SiriOrb } from "@/components/smoothui/ui/SiriOrb";

export default function App() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <SiriOrb
        size="200px"
        colors={{
          bg: "oklch(95% 0.02 264.695)",
          c1: "oklch(75% 0.15 350)",
          c2: "oklch(80% 0.12 200)",
          c3: "oklch(78% 0.14 280)",
        }}
        animationDuration={20}
      />
    </div>
  );
}

Advanced Usage

import { RichPopover } from "@/components/smoothui/ui/RichPopover";
import { ScrollableCardStack } from "@/components/smoothui/ui/ScrollableCardStack";

export default function Dashboard() {
  const cards = [
    {
      id: "1",
      name: "John Doe",
      handle: "@johndoe",
      avatar: "/avatars/john.jpg",
      video: "/videos/john.mp4",
      href: "https://twitter.com/johndoe",
    },
    // ... more cards
  ];

  return (
    <div className="space-y-8">
      <RichPopover />
      <ScrollableCardStack items={cards} />
    </div>
  );
}

Available Components

SmoothUI includes a wide variety of components:

UI Components

• SiriOrb - Animated orb with smooth color transitions
• RichPopover - Advanced popover with rich content
• ScrollableCardStack - Interactive card stack with smooth scrolling
• AnimatedInput - Input field with smooth animations
• DynamicIsland - iOS-style dynamic island component
• FluidMorph - Fluid morphing animations
• MatrixCard - Matrix-style card with particle effects

Interactive Components

• CursorFollow - Custom cursor following component
• ScrambleHover - Text scramble effect on hover
• WaveText - Animated wave text effect
• TypewriterText - Typewriter text animation

Layout Components

• ExpandableCards - Expandable card layout
• ScrollableCardStack - Stack of scrollable cards
• AppDownloadStack - App download showcase

Utility Components

• ButtonCopy - Copy button with feedback
• ClipCornersButton - Button with clipped corners
• DotMorphButton - Button with morphing dot animation

View all components →

MCP Support

SmoothUI is fully compatible with the shadcn MCP server, enabling AI assistants to discover and install components automatically.

🤖 AI Assistant Integration

With MCP support, AI assistants like Claude, Cursor, and GitHub Copilot can:

• Discover Components: Browse all available SmoothUI components
• Install Components: Automatically install components with dependencies
• Provide Usage Examples: Get code examples and integration help
• Smart Suggestions: Receive intelligent component recommendations

Quick MCP Setup

1. Configure your registry in components.json:

{
  "registries": {
    "@smoothui": "https://smoothui.dev/r/{name}.json"
  }
}

2. Install MCP server:

npx shadcn@latest mcp init --client claude
# or for Cursor: npx shadcn@latest mcp init --client cursor
# or for VS Code: npx shadcn@latest mcp init --client vscode

3. Try these prompts:

• "Show me the components in the smoothui registry"
• "Install the SiriOrb component from smoothui"
• "Create a landing page using smoothui components"

Learn more about MCP support →

Registry System

SmoothUI uses a custom registry system compatible with shadcn CLI v3. Each component includes:

Automatic Dependencies

• Package Dependencies: Required npm packages are automatically included
• Utility Files: Shared utilities like cn are automatically bundled
• Import Paths: All import paths are automatically resolved

Component Structure

When you install a component, you get:

components/smoothui/ui/
├── ComponentName.tsx    # Main component file
lib/utils/
└── cn.ts               # Utility functions (if needed)

Registry Features

• Self-contained: Each component includes all necessary dependencies
• Type-safe: Full TypeScript support with proper types
• Optimized: Components are optimized for performance
• Accessible: Built-in accessibility features

Troubleshooting

Common Issues

1. Authentication Error (401)

Error: You are not authorized to access the item

Solution: This usually happens with Vercel preview deployments. Use the production URL:

{
  "registries": {
    "@smoothui": "https://smoothui.dev/r/{name}.json"
  }
}

2. Registry Not Found

Error: The item at https://smoothui.dev/r/registry.json was not found

Solution: The search command might not work as expected. Install components directly:

npx shadcn@latest add @smoothui/siri-orb

3. Import Path Issues

Error: Cannot find module '@/lib/utils/cn'

Solution: Make sure your tsconfig.json includes the path alias:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

4. Missing Dependencies

Error: Cannot find module 'clsx'

Solution: Install missing dependencies:

pnpm add clsx tailwind-merge motion

Getting Help

• Documentation: Visit smoothui.dev for detailed documentation
• Issues: Report bugs on GitHub Issues
• Discussions: Join discussions on GitHub Discussions

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Clone the repository:

git clone https://github.com/educlopez/smoothui.git
cd smoothui

2. Install dependencies:

pnpm install

3. Start development server:

pnpm dev

4. Build registry:

pnpm run build:registry

License

This project is licensed under the MIT License - see the LICENSE file for details.