// Use hooks for complex logic or conditional rendering
const isMobile = useIsMobile();
if (isMobile) return
;
```
### Avoid Excessive Re-renders [#avoid-excessive-re-renders]
The hook only triggers re-renders when crossing the breakpoint threshold, not on every resize event.
### Test Across Devices [#test-across-devices]
Always test responsive behavior on actual devices, not just browser dev tools resizing.
***
## Related [#related]
Explore utility functions like cn() for class merging.
Learn how to create performant, accessible animations.
# Introduction (/docs/guides)
## What is SmoothUI? [#what-is-smoothui]
SmoothUI is a modern component library that brings together the best of React, Tailwind CSS, [Motion](https://motion.dev), and [GSAP](https://gsap.com) to create beautiful, accessible, and performant user interfaces. Each component is carefully crafted with smooth animations and thoughtful design principles.
## Key Features [#key-features]
* **shadcn CLI Compatible**: Install components using the familiar shadcn CLI
* **MCP Support**: AI assistants can discover and install components automatically
* **TypeScript First**: Full type safety with comprehensive TypeScript support
* **Accessible by Default**: Built with accessibility best practices
* **Dark Mode Support**: All components work seamlessly in light and dark themes
* **Customizable**: Easy to customize with Tailwind CSS classes
* **Performance Optimized**: Built with performance in mind using modern React patterns
## Get Started [#get-started]
Learn how to install SmoothUI components using shadcn CLI or manual installation methods.
Explore all available components with live demos and documentation.
## Frequently Asked Questions [#frequently-asked-questions]
Yes! SmoothUI is completely free and open source. You can use it in personal and commercial projects.
No! All animations are built-in. You can use components without any Motion or GSAP knowledge.
Absolutely! All components are built with Tailwind CSS and can be customized using standard Tailwind classes.
Yes! SmoothUI works with any React framework including Next.js, Vite, Create React App, and more.
## Contributing [#contributing]
We welcome contributions to SmoothUI! Whether you want to add new components, improve existing ones, or fix bugs, your contributions help make SmoothUI better for everyone.
* Fork the repository on GitHub
* Create a new branch for your feature or bug fix
* Make your changes and test them thoroughly
* Submit a pull request with a clear description
Check out our [contributing guide](https://github.com/educlopez/smoothui/blob/main/CONTRIBUTING.md) for more detailed information.
# Installation (/docs/guides/installation)
SmoothUI works with any React-compatible framework. Check out the dedicated setup guides:
* **[Vite + React](/docs/guides/vite)** — The simplest setup for client-side React apps
* **[Astro](/docs/guides/astro)** — Islands architecture with selective hydration
* **[Remix](/docs/guides/remix)** — Full-stack SSR with React Router v7
* **[TanStack Start](/docs/guides/tanstack-start)** — Type-safe full-stack with streaming SSR
## Installation (SmoothUI CLI) [#installation-smoothui-cli]
The SmoothUI CLI provides an interactive way to browse and install components with automatic dependency resolution.
### Add Components [#add-components]
### Add Multiple Components [#add-multiple-components]
### Interactive Mode [#interactive-mode]
### List Available Components [#list-available-components]
Run the add command without arguments to launch an interactive picker. Search and browse components by category, then select multiple components to install at once.
***
## Installation (shadcn Registry) [#installation-shadcn-registry]
SmoothUI is an official shadcn registry, so you can install components directly without any configuration. Just use the `@smoothui{:js}` namespace.
Since SmoothUI is an official registry, you don't need to add anything to your `components.json{:js}` file. Just install components directly!
### Install Components [#install-components]
Install SmoothUI components using the shadcn CLI with the `@smoothui{:js}` namespace:
### Install Multiple Components [#install-multiple-components]
### Use Components [#use-components]
Import and use the installed components in your React application:
```tsx
import { SiriOrb } from "@/components/smoothui/ui/SiriOrb"
import { RichPopover } from "@/components/smoothui/ui/RichPopover"
export default function App() {
return (
)
}
```
# MCP Server (/docs/guides/mcp)
MCP support for registry developers - Enable AI assistants to discover and use SmoothUI components.
The **shadcn MCP server** works out of the box with any shadcn-compatible registry. You do not need to do anything special to enable MCP support for your SmoothUI registry.
## Prerequisites [#prerequisites]
The MCP server works by requesting your registry index. Make sure you have a registry item file at the root of your registry named `registry.json{:js}`.
For example, if your registry is hosted at `https://smoothui.dev/r/[name].json{:js}`, you should have a file at `https://smoothui.dev/r/registry.json{:js}`.
This file must be a valid JSON file that conforms to the registry schema.
## Configuring MCP [#configuring-mcp]
Ask your registry consumers to configure your registry in their `components.json{:js}` file and install the shadcn MCP server:
**Configure your registry** in your `components.json{:js}` file:
```json title="components.json"
{
"registries": {
// [!code highlight]
"@smoothui": "https://smoothui.dev/r/{name}.json"
}
}
```
**Run the following command** in your project:
```shell title="Terminal"
pnpm dlx shadcn@latest mcp init --client claude
```
```shell title="Terminal"
npx shadcn@latest mcp init --client claude
```
```shell title="Terminal"
yarn dlx shadcn@latest mcp init --client claude
```
```shell title="Terminal"
bunx shadcn@latest mcp init --client claude
```
**Restart Claude Code** and try the following prompts:
* Show me the components in the smoothui registry
* Create a landing page using items from the smoothui registry
* Install the SiriOrb component from smoothui
**Note:** You can use `/mcp{:js}` command in Claude Code to debug the MCP server.
**Configure your registry** in your `components.json{:js}` file:
```json title="components.json"
{
"registries": {
// [!code highlight]
"@smoothui": "https://smoothui.dev/r/{name}.json"
}
}
```
**Run the following command** in your project:
```shell title="Terminal"
pnpm dlx shadcn@latest mcp init --client cursor
```
```shell title="Terminal"
npx shadcn@latest mcp init --client cursor
```
```shell title="Terminal"
yarn dlx shadcn@latest mcp init --client cursor
```
```shell title="Terminal"
bunx shadcn@latest mcp init --client cursor
```
Open **Cursor Settings** and **Enable the MCP server** for shadcn. Then try the following prompts:
* Show me the components in the smoothui registry
* Create a landing page using items from the smoothui registry
* Install the SiriOrb component from smoothui
**Configure your registry** in your `components.json{:js}` file:
```json title="components.json"
{
"registries": {
// [!code highlight]
"@smoothui": "https://smoothui.dev/r/{name}.json"
}
}
```
**Run the following command** in your project:
```shell title="Terminal"
pnpm dlx shadcn@latest mcp init --client vscode
```
```shell title="Terminal"
npx shadcn@latest mcp init --client vscode
```
```shell title="Terminal"
yarn dlx shadcn@latest mcp init --client vscode
```
```shell title="Terminal"
bunx shadcn@latest mcp init --client vscode
```
Open `.vscode/mcp.json{:js}` and click **Start** next to the shadcn server. Then try the following prompts with GitHub Copilot:
* Show me the components in the smoothui registry
* Create a landing page using items from the smoothui registry
* Install the SiriOrb component from smoothui
## Example Prompts [#example-prompts]
Once MCP is configured, you can use these prompts with your AI assistant:
Component Discovery
-
“Show me all available components in the smoothui registry”
-
“What animation components are available in smoothui?”
-
“List all interactive components from smoothui”
Component Installation
-
“Install the SiriOrb component from smoothui”
-
“Add the RichPopover component to my project”
-
“Install multiple components: SiriOrb, AnimatedInput, and ScrollableCardStack”
Component Usage
-
“Create a landing page using the SiriOrb component”
-
“Show me how to use the ScrollableCardStack component”
-
“Build a dashboard with smoothui components”
## Learn More [#learn-more]
Full overview of all AI integration options — MCP, REST API, and machine-readable catalogs.
Complete API reference for programmatic access to the component catalog.
You can also read more about the shadcn MCP protocol in the shadcn MCP documentation.
# Migration from shadcn (/docs/guides/migration-from-shadcn)
## Overview [#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.
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 [#step-1-install-the-smoothui-component]
Use either the SmoothUI CLI or the shadcn registry to add the component you want:
This installs the component to `components/smoothui/ui/` alongside your existing shadcn components in `components/ui/`.
***
## Step 2: Update Imports [#step-2-update-imports]
Replace the shadcn import with the SmoothUI import:
```tsx
// Before: shadcn/ui
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs"
// After: SmoothUI
import AnimatedTabs from "@/components/smoothui/ui/AnimatedTabs"
```
SmoothUI components use a **default export** pattern rather than named exports. Each component is a single self-contained import.
***
## Step 3: Adapt Props [#step-3-adapt-props]
SmoothUI components have their own prop interfaces. Here are the common patterns to adjust:
### Composition vs Props [#composition-vs-props]
shadcn uses a **compound component** pattern with multiple named exports. SmoothUI components are **single components** that accept data as props:
```tsx
// shadcn: Compound components
Tab 1
Tab 2
Content 1
Content 2
// SmoothUI: Data-driven props
Content 1
### Create a New Next.js Project [#1-create-a-new-nextjs-project]
If you're starting from scratch, create a new Next.js project with TypeScript and Tailwind CSS:
```bash
npx create-next-app@latest my-smoothui-app --typescript --tailwind --app
cd my-smoothui-app
```
This scaffolds a Next.js project with App Router, TypeScript, and Tailwind CSS 4 pre-configured.
### Tailwind CSS 4 Configuration [#2-tailwind-css-4-configuration]
If you used `create-next-app` with the `--tailwind` flag, Tailwind CSS 4 is already configured. Your `app/globals.css` should contain:
```css title="app/globals.css"
@import "tailwindcss";
```
If you're adding Tailwind to an existing project, install it:
Then configure PostCSS:
```js title="postcss.config.mjs"
const config = {
plugins: {
"@tailwindcss/postcss": {},
},
};
export default config;
```
### Install Motion [#3-install-motion]
SmoothUI animations are powered by Motion (Framer Motion). Install it as a dependency:
### Initialize shadcn/ui [#4-initialize-shadcnui]
SmoothUI builds on the shadcn ecosystem. Initialize shadcn in your project:
Follow the prompts to configure your project. This sets up `components.json` and the `cn()` utility that SmoothUI components depend on.
## Installing SmoothUI Components [#installing-smoothui-components]
### Using the SmoothUI CLI [#using-the-smoothui-cli]
### Create a New TanStack Start Project [#1-create-a-new-tanstack-start-project]
If you're starting from scratch, create a new TanStack Start project:
Then install dependencies:
### Set Up Tailwind CSS 4 [#2-set-up-tailwind-css-4]
TanStack Start uses Vinxi, which is built on Vite. Install Tailwind CSS and the Vite plugin:
Add the Tailwind CSS Vite plugin to your app config:
```ts title="app.config.ts"
import { defineConfig } from "@tanstack/react-start/config";
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
vite: {
plugins: () => [tailwindcss()],
},
});
```
Create or update your main CSS file with the Tailwind import:
```css title="app/styles/app.css"
@import "tailwindcss";
```
Import the stylesheet in your root route (typically `app/routes/__root.tsx{:tsx}`):
```tsx title="app/routes/__root.tsx"
import { createRootRoute, Outlet } from "@tanstack/react-router";
import appCss from "@/styles/app.css?url";
export const Route = createRootRoute({
head: () => ({
links: [{ rel: "stylesheet", href: appCss }],
}),
component: RootComponent,
});
function RootComponent() {
return (
);
}
```
### Install Motion [#3-install-motion]
SmoothUI animations are powered by Motion (Framer Motion). Install it as a dependency:
### Configure Path Aliases [#4-configure-path-aliases]
SmoothUI components use the `@/{:ts}` path alias. Configure it in your `tsconfig.json{:json}`:
```json title="tsconfig.json"
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./app/*"]
}
}
}
```
TanStack Start resolves TypeScript paths automatically via Vinxi's Vite integration. If path aliases don't resolve at runtime, add `vite-tsconfig-paths{:ts}` to your app config:
```ts title="app.config.ts"
import { defineConfig } from "@tanstack/react-start/config";
import tailwindcss from "@tailwindcss/vite";
import tsconfigPaths from "vite-tsconfig-paths";
export default defineConfig({
vite: {
plugins: () => [tailwindcss(), tsconfigPaths()],
},
});
```
## Installing SmoothUI Components [#installing-smoothui-components]
### Using the SmoothUI CLI [#using-the-smoothui-cli]