✨ UniqueUI

A collection of beautiful, animated React components you can copy-paste into your apps.
Built with React 19, Motion, and Tailwind CSS 4.

Components • Installation • shadcn CLI • Commands • Setup Guide • Examples • Customization • Development • Troubleshooting

Overview

UniqueUI is an open-source component library focused on micro-interactions and animations. Instead of installing a heavy package, you pick the components you need and add them directly to your project via the CLI — no runtime dependency on UniqueUI itself.

Key features:

🎯 Copy-paste architecture — Components live in your codebase, fully customizable
🎨 30 animated components — From subtle to spectacular
⚡ CLI for instant setup — npx uniqueui init → npx uniqueui add <component> (or install via shadcn CLI from the published registry)
🧩 Zero lock-in — Uses standard React, Motion, and Tailwind CSS
📱 Dark-first design — Every component looks great out of the box

Repo Map

If you are exploring or contributing to the repository, these are the main places to start:

apps/www — Next.js docs and demo site
packages/cli — published uniqueui-cli
registry/ — component source, metadata, and registry config
scripts/ — build, verification, and release helpers
docs/ — architecture notes and maintainer documentation

Start here:

Want to use UniqueUI in an app? Continue with the installation section below.
Want to contribute a component or fix? Read CONTRIBUTING.md.
Want to run the docs site locally? Run pnpm dev from the repo root or read BUILD.md.

Repository development uses pnpm workspaces. Root commands in this repo assume pnpm, not npm.

Components

Component	Category	Description
Moving Border	Effects & Animations	SVG-path-tracing animated border that orbits a button or card.
Typewriter Text	Text	Character-by-character typing with blinking cursor, configurable speed, and delete-retype loop.
3D Tilt Card	Cards	Perspective-shifting card that tilts toward the cursor with parallax layers and glare overlay.
Spotlight Card	Cards	Card with a radial spotlight that follows the mouse cursor across its surface.
Aurora Background	Backgrounds	Flowing aurora borealis gradient animation using layered blurred blobs.
Animated Tabs	Navigation & Overlays	Tab bar with a sliding pill that morphs between active tabs using layout animation.
Magnetic Button	Effects & Animations	Button that stretches toward the cursor when nearby and snaps back with spring physics.
Infinite Marquee	Effects & Animations	Seamless infinite-scrolling ticker with pause-on-hover and variable speed.
Scroll Reveal	Effects & Animations	Elements animate into view when they enter the viewport, with 6 animation presets.
Skeleton Shimmer	Effects & Animations	Skeleton loading placeholders with animated shimmer gradient sweep and pulse fade.
Morphing Modal	Navigation & Overlays	Modal that expands from the trigger element with spring physics and backdrop blur.
Gradient Text Reveal	Text	Word-by-word text reveal with gradient coloring and blur-to-clear spring animation.
Scramble Text	Text	Matrix-style text scramble effect that resolves characters left-to-right.
Meteors Card	Cards	Card with animated meteor/shooting star particles falling through the background.
Flip Card	Cards	3D card flip with spring physics, supporting hover or click triggers.
Dot Grid Background	Backgrounds	Interactive dot-grid pattern with a glowing cursor-following effect.
Floating Dock	Navigation & Overlays	macOS-style dock with magnetic scaling, spring physics, and tooltips.
Confetti Burst	Effects & Animations	Click-triggered confetti particle explosion with customizable colors and physics.
Drawer Slide	Navigation & Overlays	Slide-out drawer panel with drag-to-dismiss, spring physics, and backdrop blur.
Notification Stack	Navigation & Overlays	Stacked toast notifications with auto-dismiss progress, sliding animations, and multiple types.
Animated Timeline	Effects & Animations	Scroll-triggered timeline with 4 distinct Motion.dev animation variants: vertical spring, horizontal growing line, alternating cards, and numbered steps.
Nested Comments	Social & Interaction	Threaded comment section with infinite nesting, animated expand/collapse, inline reply composer, and spring-physics like button.
Hover Reveal Card	Cards	Card that displays an image with teaser content, then slides up a full details panel on hover with staggered Motion.dev animations.
Bento Grid	Cards	Responsive masonry-style grid layout with staggered scroll-reveal entrance, hover border glow, and icon scale animations per cell.
Particle Field	Backgrounds	Canvas-based floating particles with mouse-repulsion physics and responsive connecting lines.
Horizontal Scroll Gallery	Effects & Animations	Converts vertical scroll into horizontal movement with momentum physics for immersive galleries.
Radial Menu	Navigation & Overlays	Circular flyout menu that bursts items outward from a center trigger with staggered spring animation.
Cursor Trail	Cursor Effects	Glowing trail that follows the cursor with decay physics, like a sparkler or comet tail.
Pen Cursor	Cursor Effects	Spring-smoothed stroke with fast-fading ink tail; system cursor visible by default; grey by default.
Mini Mac Keyboard	Decorative	Compact decorative Mac-style keyboard strip for hero/device scenes and desktop mockups.
Macbook Mock	Device Mockups	Animated 3D MacBook-style frame with reveal screen, dynamic island states, and accessible interactions.

Installation

Requirements

Requirement	Version	Notes
Node.js (CLI users)	≥ 18	20 LTS / 22 LTS recommended. The monorepo itself uses Node 24 — that's for contributors only and does not affect end users of `uniqueui-cli`.
React	18 or 19	Components are written to run on both.
Tailwind CSS	3.4+ or 4.x	The CLI detects which major you're on. v3: merges `theme.extend` into your `tailwind.config.*`. v4: appends a marker-wrapped `@theme` snippet to the file at `components.json#tailwind.css`. Idempotent on re-runs; respects `--dry-run`. See the compatibility matrix.

All components use Motion (formerly Framer Motion). The CLI installs motion automatically.

Option A — Run directly (recommended)

npx uniqueui <command>
# or
pnpm dlx uniqueui <command>
# or
bunx uniqueui <command>

Option B — Install globally

npm install -g uniqueui-cli
uniqueui <command>

Option C — Install as a dev dependency

npm install -D uniqueui-cli
npx uniqueui <command>

Quick Start

# 1. Initialize UniqueUI in your project
npx uniqueui init

# 2. Add a component
npx uniqueui add spotlight-card

If you use shadcn/ui in your app, you can add the same components with the shadcn CLI instead — see Installing with the shadcn CLI.

import { SpotlightCard } from "@/components/ui/spotlight-card";

export default function Page() {
  return (
    <SpotlightCard>
      <h2>Hover me</h2>
      <p>Watch the spotlight follow your cursor.</p>
    </SpotlightCard>
  );
}

Commands

Command	Description
`uniqueui init`	Set up UniqueUI config for your project — creates `components.json`, installs base dependencies, and adds the `cn` utility
`uniqueui add <component>`	Fetch a component from the registry, install dependencies, and write it to your project
`uniqueui list`	Display all components available in the registry
`uniqueui info <component>`	Print metadata (deps, files, Tailwind requirements) for one component without writing anything
`uniqueui doctor`	Diagnose your project's setup (Node, Tailwind, `components.json`, `@/*` alias, `cn` helper)
`uniqueui search <query>`	Fuzzy search registry components by name, title, or description

`init` details

You'll be prompted for:

Prompt	Default	Description
Components directory	`components/ui`	Where component files will be saved
TypeScript	`yes`	Whether to use `.tsx` files
Tailwind config path	`tailwind.config.ts`	Path to your Tailwind configuration

Creates components.json in your project root:

{
  "componentsDir": "components/ui",
  "typescript": true,
  "tailwindConfig": "tailwind.config.ts"
}

`add` details

npx uniqueui add <component-name> [--url <custom-registry-url>]

What happens:

Fetches the component source from the GitHub registry
Installs any required npm dependencies (motion, clsx, tailwind-merge)
Merges required Tailwind animations/keyframes into your config
Writes the component .tsx file to your configured directory
Writes a utils/cn.ts helper file (if not already present)

Installing with the shadcn CLI

Every component is also published in the shadcn registry format when the docs site is built. After pnpm build:registry, files appear under apps/www/public/r/ in this repo; on production they are served from https://uniqueui-platform.vercel.app/r/.

Artifact	Purpose
`https://uniqueui-platform.vercel.app/r/<slug>.json`	Single component (registry-item schema)
`https://uniqueui-platform.vercel.app/r/registry.json`	Full catalog (registry schema)

Add one component:

npx shadcn@latest add https://uniqueui-platform.vercel.app/r/moving-border.json -y

Requirements:

A project that already matches what the shadcn CLI expects: components.json, Tailwind v3-style setup, and @/lib/utils exporting cn (UniqueUI source files import import { cn } from "@/lib/utils"). Run npx shadcn@latest init in a new Next.js app if you do not have this yet.
The registry item installs the UI file as registry:component at components/ui/<slug>.tsx (with the src/ prefix if your app uses the App Router src/ layout). Tailwind extras from the component are merged into your tailwind.config when present.
The cn util file is not bundled in the shadcn item (your app should already have it from shadcn init), which matches typical shadcn projects.

Local / PR verification: point shadcn add at an absolute path to a built file, e.g.
npx shadcn@latest add "/path/to/uniqueui/apps/www/public/r/moving-border.json" -y.

Automated check: from the repo root, pnpm test:e2e:shadcn creates a fresh Next app, runs shadcn add for every component, writes preview routes from docs usageCode, and runs next build.

Project Setup Guide

Next.js Setup

# 1. Create project (skip if you already have one)
npx create-next-app@latest my-app --typescript --tailwind --app
cd my-app

# 2. Initialize UniqueUI
npx uniqueui init
# Components directory: components/ui
# Tailwind config: tailwind.config.ts

# 3. Add components
npx uniqueui add moving-border
npx uniqueui add aurora-background

Ensure tsconfig.json has the @ alias (Next.js sets this up by default):

{
  "compilerOptions": {
    "paths": { "@/*": ["./*"] }
  }
}

// app/page.tsx
import { AuroraBackground } from "@/components/ui/aurora-background";
import { Button } from "@/components/ui/moving-border";

export default function Home() {
  return (
    <AuroraBackground>
      <div className="text-center text-white z-10">
        <h1 className="text-5xl font-bold mb-6">Welcome</h1>
        <Button borderRadius="1.75rem">Get Started</Button>
      </div>
    </AuroraBackground>
  );
}

Vite + React Setup

npm create vite@latest my-app -- --template react-ts
cd my-app && npm install
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Update vite.config.ts to add the @ alias:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import path from "path";

export default defineConfig({
  plugins: [react()],
  resolve: { alias: { "@": path.resolve(__dirname, "./src") } },
});

npx uniqueui init   # Components directory: src/components/ui
npx uniqueui add typewriter-text

Create React App Setup

npx create-react-app my-app --template typescript
cd my-app
npm install -D tailwindcss && npx tailwindcss init
npm install -D @craco/craco

Create craco.config.js:

const path = require("path");
module.exports = { webpack: { alias: { "@": path.resolve(__dirname, "src") } } };

npx uniqueui init
npx uniqueui add magnetic-button

Usage Examples

Hero section with Aurora + Moving Border

import { AuroraBackground } from "@/components/ui/aurora-background";
import { Button } from "@/components/ui/moving-border";
import { TypewriterText } from "@/components/ui/typewriter-text";

export default function Hero() {
  return (
    <AuroraBackground className="min-h-screen">
      <div className="text-center text-white z-10 px-4">
        <h1 className="text-6xl font-bold mb-4">
          Build with{" "}
          <TypewriterText words={["Motion", "Style", "UniqueUI"]} className="text-purple-400" />
        </h1>
        <Button borderRadius="1.75rem" className="bg-zinc-950 text-white mt-6">
          Get Started
        </Button>
      </div>
    </AuroraBackground>
  );
}

Features section with Scroll Reveal

import { ScrollRevealGroup } from "@/components/ui/scroll-reveal";
import { SpotlightCard } from "@/components/ui/spotlight-card";

const features = [
  { title: "Animated", desc: "Every component ships with beautiful motion." },
  { title: "Copy-paste", desc: "You own the code. No lock-in." },
  { title: "Tailwind", desc: "Styled with utility classes you already know." },
];

export default function Features() {
  return (
    <ScrollRevealGroup animation="fade-up" staggerDelay={0.15} className="grid md:grid-cols-3 gap-6 p-12">
      {features.map((f) => (
        <SpotlightCard key={f.title} className="p-6 rounded-xl">
          <h3 className="text-xl font-bold text-white mb-2">{f.title}</h3>
          <p className="text-neutral-400 text-sm">{f.desc}</p>
        </SpotlightCard>
      ))}
    </ScrollRevealGroup>
  );
}

Navigation with Floating Dock

import { FloatingDock } from "@/components/ui/floating-dock";
import { Home, User, Briefcase, Mail } from "lucide-react";

const navItems = [
  { id: "home", label: "Home", icon: <Home />, href: "/" },
  { id: "about", label: "About", icon: <User />, href: "/about" },
  { id: "work", label: "Work", icon: <Briefcase />, href: "/work" },
  { id: "contact", label: "Contact", icon: <Mail />, href: "/contact" },
];

export default function Nav() {
  return (
    <div className="fixed bottom-6 left-1/2 -translate-x-1/2">
      <FloatingDock items={navItems} />
    </div>
  );
}

Customization

Since you own the component files after installing, you can customize anything:

// Change colors to your brand
<Button className="bg-indigo-950 text-indigo-100 border-indigo-700">Click me</Button>

// Slow down typewriter typing
<TypewriterText words={["Hello"]} typingSpeed={200} deletingSpeed={100} />

// Add responsive / dark-mode variants
<SpotlightCard className="md:p-8 lg:p-12 dark:bg-neutral-950">
  {/* your content */}
</SpotlightCard>

Compatibility

Tailwind CSS: Native support for v3 and v4
Shadcn UI: Drop-in compatible — both use the copy-paste model and cn utility
Other React UI Libraries: No runtime dependency means zero conflicts with Chakra UI, Radix, NextUI, etc.

Development

Tech Stack

Layer	Technology
Monorepo	pnpm workspaces
Showcase	Next.js (App Router)
Framework	React 19
Styling	Tailwind CSS 4
Animations	Motion 12 (motion/react)
Icons	Lucide React
CLI	Commander + Chalk + Ora

Getting Started

git clone https://github.com/pras75299/uniqueui.git
cd uniqueui
pnpm install

# Run the showcase site
cd apps/www
pnpm dev

The showcase site will be available at http://localhost:3000.

Building

# Build the showcase site
cd apps/www && pnpm build

# Build the CLI
cd packages/cli && pnpm build

# Build the registry (from root)
pnpm build:registry

# Run component E2E (UniqueUI CLI + full page matrix + build)
npx ts-node scripts/test-all-components.ts

# Run shadcn CLI E2E (install each component from apps/www/public/r/*.json + build)
pnpm test:e2e:shadcn
# Smoke (first N only): SHADCN_E2E_LIMIT=3 pnpm test:e2e:shadcn
# Afterward, `npm run dev` — home lists each component; **Open preview** goes to `/preview/[slug]` (same usageCode as the docs site, importing from `src/components/ui/`).

Project Structure

uniqueui/
├── apps/
│   └── www/                    # Next.js showcase & documentation site
│       ├── app/
│       │   ├── page.tsx        # Landing page
│       │   ├── components/     # Component documentation pages
│       │   │   ├── page.tsx    # Component listing
│       │   │   └── [slug]/     # Individual component pages
│       │   ├── layout.tsx      # Root layout
│       │   └── globals.css     # Global styles & keyframes
│       ├── components/
│       │   └── ui/             # Synced UI copies (from registry)
│       ├── public/
│       │   ├── registry/     # Split registry for uniqueui add (index + per slug)
│       │   └── r/            # shadcn registry items (*.json) + r/registry.json
│       └── config/
│           ├── components.ts   # Component metadata (name, slug, icon, description)
│           └── demos.tsx       # Component demo configurations
├── packages/
│   └── cli/                    # UniqueUI CLI tool
│       └── src/
│           ├── index.ts        # CLI entry point (Commander)
│           └── commands/
│               ├── init.ts     # `uniqueui init` command
│               ├── add.ts      # `uniqueui add` command
│               └── list.ts     # `uniqueui list` command
├── registry/                   # Component source files + config
│   ├── config.ts               # Registry configuration (dependencies, files)
│   └── moving-border/          # One folder per component slug
│       └── component.tsx       # Component source file
├── scripts/
│   ├── build-registry.ts      # Builds registry artifacts and syncs docs UI copies
│   ├── test-all-components.ts # E2E: uniqueui add + generated pages + build
│   └── test-shadcn-all-components.ts # E2E: shadcn add + previews + build
├── registry.json               # Generated registry manifest
├── pnpm-workspace.yaml         # Workspace configuration
└── package.json                # Root package.json

How It Works

Registry (GitHub)
       │
       ├── npx uniqueui add <component>
       │        ▼
       │   Your project (components.json paths, utils/cn)
       │
       └── npx shadcn add https://uniqueui-platform.vercel.app/r/<slug>.json
                ▼
            Your project (shadcn components.json, @/lib/utils)

Registry — Each component is defined in registry/config.ts and points at files like registry/<slug>/component.tsx. build-registry.ts outputs registry.json, split files under apps/www/public/registry/, shadcn-format items under apps/www/public/r/, and synced docs UI copies.
UniqueUI CLI — Fetches the hosted registry, writes files to your project, and installs npm dependencies (and can add utils/cn.ts).
shadcn CLI — Consumes the same component source via public/r/<slug>.json URLs; expects a standard shadcn project layout and @/lib/utils for cn.
Showcase — The apps/www Next.js site serves as marketing landing page and component documentation with live previews and install commands.

Troubleshooting

`Cannot find module '@/utils/cn'`

Update the import to match your project's cn location:

import { cn } from "@/lib/utils"; // Next.js shadcn-style setup

Or re-run npx uniqueui add <component> to regenerate utils/cn.ts.

`Module not found: Can't resolve 'motion/react'`

npm install motion

Tailwind animations not working

Ensure content in tailwind.config.ts includes component files:

content: [
  "./app/**/*.{ts,tsx}",
  "./components/**/*.{ts,tsx}",  // ← required
],

Component file not appearing after `add`

Check components.json to confirm componentsDir matches your actual directory:

cat components.json

`npx uniqueui` — command not found

node --version  # must be v18 or higher

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/my-component)
Add your component to registry/ and update registry/config.ts
Update registry/docs.json for docs metadata and apps/www/config/demos.tsx for the live demo
Run pnpm build:registry to regenerate registry.json, refresh apps/www/public/registry/* and apps/www/public/r/*, sync apps/www/components/ui/*, and generate apps/www/config/components.ts plus apps/www/config/docs-scenarios.ts
Run pnpm build to ensure everything compiles
Submit a pull request

Links

License

This project is open source and available under the MIT License.

Built by @pras75299

Name		Name	Last commit message	Last commit date
Latest commit History 432 Commits
.agent/skills/frontend		.agent/skills/frontend
.changeset		.changeset
.claude		.claude
.cursor		.cursor
.github		.github
.hallmark		.hallmark
.husky		.husky
apps/www		apps/www
docs		docs
packages/cli		packages/cli
registry		registry
scripts		scripts
utils		utils
.cursorrules		.cursorrules
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmrc		.npmrc
.opencode.json		.opencode.json
.windsurfrules		.windsurfrules
AGENTS.md		AGENTS.md
BUILD.md		BUILD.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
COMPONENT_LIBRARY.md		COMPONENT_LIBRARY.md
CONTRIBUTING.md		CONTRIBUTING.md
GEMINI.md		GEMINI.md
README.md		README.md
SECURITY.md		SECURITY.md
entities.json		entities.json
knip.json		knip.json
mempalace.yaml		mempalace.yaml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
registry.json		registry.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json
vercel.json		vercel.json
vitest.workspace.ts		vitest.workspace.ts

Folders and files

Latest commit

History

Repository files navigation

✨ UniqueUI

Overview

Repo Map

Components

Installation

Requirements

Option A — Run directly (recommended)

Option B — Install globally

Option C — Install as a dev dependency

Quick Start

Commands

init details

add details

Installing with the shadcn CLI

Project Setup Guide

Next.js Setup

Vite + React Setup

Create React App Setup

Usage Examples

Hero section with Aurora + Moving Border

Features section with Scroll Reveal

Navigation with Floating Dock

Customization

Compatibility

Development

Tech Stack

Getting Started

Building

Project Structure

How It Works

Troubleshooting

Cannot find module '@/utils/cn'

Module not found: Can't resolve 'motion/react'

Tailwind animations not working

Component file not appearing after add

npx uniqueui — command not found

Contributing

Links

License

About

Resources

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`init` details

`add` details

`Cannot find module '@/utils/cn'`

`Module not found: Can't resolve 'motion/react'`

Component file not appearing after `add`

`npx uniqueui` — command not found

Packages