Getting Started

Prerequisites

Before you begin, make sure you have:

• Node.js 18.17 or later
• React 19 or later
• Tailwind CSS 4 or later configured in your project
• A package manager: pnpm (recommended), npm, yarn, or bun

Step 1: Set Up a Next.js Project

If you already have a project, skip to Step 2.

npx create-next-app@latest my-app --typescript --tailwind --app
cd my-app

Step 2: Initialize shadcn/ui

SmoothUI builds on the shadcn ecosystem. If you haven't initialized shadcn yet:

pnpm dlx shadcn@latest init

Follow the prompts to configure your project. This sets up the components.json file and the utility functions SmoothUI components depend on.

Step 3: Install Your First Component

SmoothUI is an official shadcn registry — no extra configuration needed. Install a component using either the SmoothUI CLI or the shadcn CLI:

Option A: SmoothUI CLI (recommended)

pnpm dlx smoothui-cli@latest add smooth-button

Option B: shadcn Registry

pnpm dlx shadcn@latest add @smoothui/smooth-button

Both methods automatically install the component files and any required dependencies (like motion).

Step 4: Use the Component

Import and render the component in your page:

import SmoothButton from "@/components/smoothui/ui/SmoothButton"

export default function Home() {
  return (
    <main className="flex min-h-screen items-center justify-center">
      <SmoothButton>
        Click me
      </SmoothButton>
    </main>
  )
}

Start your dev server to see it in action:

pnpm dev

You should see an animated button with smooth hover and press transitions.

Step 5: Explore More Components

Browse the full component library and install anything you need:

pnpm dlx smoothui-cli@latest add

Running the add command without arguments launches interactive mode where you can search and select multiple components at once.

Popular Components to Try

• Expandable Cards — Cards that expand with smooth spring animations
• Animated Tabs — Tab navigation with animated indicator
• Siri Orb — Mesmerizing animated gradient orb
• Rich Popover — Contextual popover with fluid transitions
• Dynamic Island — Apple-inspired adaptive container

How It Works

SmoothUI components are copied into your project — not installed as a dependency. This means:

1. Full ownership — You can customize any component to fit your needs
2. No version lock-in — Components don't break when a library updates
3. Tree-shakeable — Only the components you install are in your bundle
4. Type-safe — Full TypeScript support with exported prop types

Components are installed to components/smoothui/ui/ by default and use:

• Motion for spring-based animations
• Tailwind CSS for styling
• shadcn/ui primitives where applicable

Next Steps

• Installation methods — Learn about all installation options in detail
• Animation best practices — Understand how SmoothUI handles animations
• Design principles — The philosophy behind SmoothUI components
• SmoothUI vs shadcn — How SmoothUI complements shadcn/ui