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

Framework guides

Already have a project? Jump to the framework-specific setup:

Next.js — Recommended for most projects
Vite + React — Client-side React apps
Astro — Islands architecture
Remix — Full-stack SSR
TanStack Start — Type-safe full-stack

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:

app/page.tsx

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
Tabs — Tab navigation with motion 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:

Full ownership — You can customize any component to fit your needs
No version lock-in — Components don't break when a library updates
Tree-shakeable — Only the components you install are in your bundle
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

Getting Started