Step-by-step guide to replacing shadcn/ui components with animated SmoothUI equivalents.

Overview

SmoothUI is designed to complement shadcn/ui, not replace it entirely. This guide covers how to swap specific shadcn components with their SmoothUI animated equivalents when you want to add motion and polish to your interface.

Non-Breaking Migration

SmoothUI components are additive. You can migrate one component at a time without affecting the rest of your application. Both shadcn and SmoothUI components can coexist in the same project.

Step 1: Install the SmoothUI Component

Use either the SmoothUI CLI or the shadcn registry to add the component you want:

pnpm dlx smoothui-cli@latest add tabs

This installs the component to components/smoothui/ui/ alongside your existing shadcn components in components/ui/.

Step 2: Update Imports

Replace the shadcn import with the SmoothUI import:

// Before: shadcn/ui
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"

// After: SmoothUI
import Tabs from "@/components/smoothui/ui/Tabs"

SmoothUI components use a default export pattern rather than named exports. Each component is a single self-contained import.

Step 3: Adapt Props

SmoothUI components have their own prop interfaces. Here are the common patterns to adjust:

Composition vs Props

shadcn uses a compound component pattern with multiple named exports. SmoothUI components are single components that accept data as props:

// shadcn: Compound components
<Tabs defaultValue="tab1">
  <TabsList>
    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
  </TabsList>
  <TabsContent value="tab1">Content 1</TabsContent>
  <TabsContent value="tab2">Content 2</TabsContent>
</Tabs>

// SmoothUI: Data-driven props
<Tabs
  tabs={[
    { label: "Tab 1", content: <div>Content 1</div> },
    { label: "Tab 2", content: <div>Content 2</div> },
  ]}
/>

Styling

Both shadcn and SmoothUI use Tailwind CSS. SmoothUI components accept a className prop for customization:

// Both support className for custom styling
<Tabs className="w-full max-w-md" tabs={tabs} />

Component Mapping Reference

Below is a mapping of shadcn components to their SmoothUI animated equivalents:

shadcn/ui Component	SmoothUI Equivalent	Key Differences
`Tabs`	Tabs	Animated sliding indicator, data-driven API
`Dialog`	Dialog	Spring entrance animation, controlled via `isOpen`/`onClose`
`Toast` / `Sonner`	Toast	Animated entrance/exit with spring physics
`Accordion`	Accordion	Smooth height animation with spring easing
`Tooltip`	Tooltip	Spring-based show/hide with configurable delay
`DropdownMenu`	Dropdown Menu	Animated open/close with spring transitions
`Input`	Animated Input	Floating label animation, focus effects
`Toggle`	Morph Toggle	Spring-based toggle with smooth state transitions
`Progress`	Progress	Animated fill with spring physics
`Skeleton`	Skeleton Loader	Enhanced shimmer animation
`Avatar`	Animated Avatar Group	Staggered entrance, hover expansion

Disabling Animations

If you need to disable animations for specific instances (for example, in a performance-critical area), SmoothUI components respect the system prefers-reduced-motion setting automatically.

To programmatically control animation behavior, you can wrap components and use the Motion library's MotionConfig provider:

import { MotionConfig } from "motion/react"

// Disable all animations within this subtree
<MotionConfig reducedMotion="always">
  <Tabs tabs={tabs} />
</MotionConfig>

// Respect system setting (default behavior)
<MotionConfig reducedMotion="user">
  <Tabs tabs={tabs} />
</MotionConfig>

Migration Checklist

For each component you migrate:

Install the SmoothUI component via CLI
Update the import path from @/components/ui/ to @/components/smoothui/ui/
Adjust the JSX from compound component pattern to SmoothUI's prop-based API
Verify the component renders correctly in development
Test keyboard navigation still works as expected
Test with prefers-reduced-motion enabled to verify graceful degradation
Remove the old shadcn component file if it is no longer used elsewhere

Keeping Both

You don't have to choose one or the other. A common pattern is:

shadcn/ui for form primitives, data tables, and areas where animation adds no value
SmoothUI for hero sections, interactive cards, navigation, and anywhere you want to add visual delight

Both libraries use Tailwind CSS and share the same design token system, so they integrate seamlessly.

Migration from shadcn