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)
      • 2. Registry Not Found
      • 3. Import Path Issues
      • 4. Missing Dependencies
    • Getting Help
  • Contributing
    • Development Setup
  • License

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 CLInpx 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 componentnpx smoothui-cli add siri-orb
# Add multiple componentsnpx smoothui-cli add siri-orb rich-popover animated-input
# Interactive mode - browse and select componentsnpx smoothui-cli add
# List all available componentsnpx 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 componentnpx shadcn@latest add @smoothui/siri-orb
# Install multiple componentsnpx 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 [blocked]

3. Set up utilities:

# Create lib/utils/cn.tsmkdir -p lib/utils

// lib/utils/cn.tsimport { 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 filelib/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 [blocked] for details.

Development Setup

1. Clone the repository:

git clone https://github.com/educlopez/smoothui.gitcd 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 [blocked] file for details.