aceternity-ui

# Aceternity UI

## Overview

Aceternity UI is a **copy-paste** component library — not an npm package. You copy the component code directly into your project, giving you full ownership and customization power. Components are built with Framer Motion and Tailwind CSS.

**Key traits:**
- Copy-paste approach (no runtime dependency)
- Framer Motion for physics-based animations
- Tailwind CSS for styling
- Next.js / React compatible
- TypeScript source included

## Setup

### Install dependencies

```bash
npm install framer-motion clsx tailwind-merge
```

### Add the `cn` utility

```ts
// lib/utils.ts
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}
```

### Configure Tailwind

```js
// tailwind.config.ts — add animations
module.exports = {
  content: ["./src/**/*.{ts,tsx}"],
  theme: {
    extend: {
      animation: {
        spotlight: "spotlight 2s ease .75s 1 forwards",
        shimmer: "shimmer 2s linear infinite",
        "move-to-right": "move-to-right 2s linear infinite",
      },
      keyframes: {
        spotlight: {
          "0%": { opacity: "0", transform: "translate(-72%, -62%) scale(0.5)" },
          "100%": { opacity: "1", transform: "translate(-50%, -40%) scale(1)" },
        },
        shimmer: {
          from: { backgroundPosition: "0 0" },
          to: { backgroundPosition: "-200% 0" },
        },
      },
    },
  },
};
```

## Top 5 Components with Code

### 1. 3D Card Effect — tilt on hover

```tsx
// components/ui/3d-card.tsx
"use client";
import { useRef, useState } from "react";
import { motion } from "framer-motion";
import { cn } from "@/lib/utils";

export const CardContainer = ({ children, className }: { children: React.ReactNode; className?: string }) => {
  const containerRef = useRef<HTMLDivElement>(null);
  const [rotateX, setRotateX] = useState(0);
  const [rotateY, setRotateY] = useState(0);

  const handleMouseMove = (e: React.MouseEvent<HTMLDivElement>) => {
    if (!containerRef.current) return;
    const { left, top, width, height } = containerRef.current.getBoundingClientRect();
    const x = (e.clientX - left - width / 2) / 25;
    const y = (e.clientY - top - height / 2) / 25;
    setRotateX(-y);
    setRotateY(x);
  };

  return (
    <div
      ref={containerRef}
      onMouseMove={handleMouseMove}
      onMouseLeave={() => { setRotateX(0); setRotateY(0); }}
      className={cn("group/card perspective-1000", className)}
      style={{ perspective: "1000px" }}
    >
      <motion.div
        animate={{ rotateX, rotateY }}
        transition={{ type: "spring", stiffness: 300, damping: 30 }}
        style={{ transformStyle: "preserve-3d" }}
      >
        {children}
      </motion.div>
    </div>
  );
};

export const CardBody = ({ children, className }: { children: React.ReactNode; className?: string }) => (
  <div className={cn("h-96 w-96 rounded-xl border border-white/10 bg-gray-900 p-6", className)}>
    {children}
  </div>
);

// Usage
export function PricingCard() {
  return (
    <CardContainer>
      <CardBody className="flex flex-col justify-between p-8">
        <h3 className="text-2xl font-bold text-white">Pro Plan</h3>
        <p className="text-4xl font-bold text-white">$29<span className="text-lg text-gray-400">/mo</span></p>
        <button className="rounded-lg bg-white px-6 py-3 font-semibold text-black">Get Started</button>
      </CardBody>
    </CardContainer>
  );
}
```

### 2. Background Beams — animated gradient beams

```tsx
// components/ui/background-beams.tsx
"use client";
import { cn } from "@/lib/utils";

export function BackgroundBeams({ className }: { className?: string }) {
  return (
    <div className={cn("absolute inset-0 overflow-hidden", className)}>
      <svg
        className="absolute h-full w-full"
        xmlns="http://www.w3.org/2000/svg"
      >
        <defs>
          <radialGradient id="beam1" cx="50%" cy="0%" r="50%">
            <stop offset="0%" stopColor="#6366f1" stopOpacity="0.3" />
            <stop offset="100%" stopColor="transparent" stopOpacity="0" />
          </radialGradient>
          <radialGradient id="beam2" cx="20%" cy="50%" r="40%">
            <stop offset="0%" stopColor="#8b5cf6" stopOpacity="0.2" />
            <stop offset="100%" stopColor="transparent" stopOpacity="0" />
          </radialGradient>
        </defs>
        <rect width="100%" height="100%" fill="url(#beam1)" />
        <rect width="100%" height="100%" fill="url(#beam2)" />
        {/* Animated lines */}
        {[...Array(6)].map((_, i) => (
          <line
            key={i}
            x1={`${(i + 1) * 15}%`}
            y1="0%"
            x2={`${(i + 1) * 15 + 10}%`}
            y2="100%"
            stroke={`hsl(${240 + i * 20}, 70%, 60%)`}
            strokeWidth="1"
            strokeOpacity="0.15"
          />
        ))}
      </svg>
    </div>
  );
}

// Usage
export function HeroSection() {
  return (
    <div className="relative flex h-screen flex-col items-center justify-center bg-black">
      <BackgroundBeams />
      <h1 className="relative z-10 text-6xl font-bold text-white">
        Build the Future
      </h1>
      <p className="relative z-10 mt-4 text-xl text-gray-400">
        The platform for modern teams
      </p>
    </div>
  );
}
```

### 3. Spotlight — cursor-following light effect

```tsx
// components/ui/spotlight.tsx
"use client";
import { useRef, useState, useCallback } from "react";
import { motion } from "framer-motion";
import { cn } from "@/lib/utils";

export function Spotlight({ className }: { className?: string }) {
  const divRef = useRef<HTMLDivElement>(null);
  const [position, setPosition] = useState({ x: 0, y: 0 });
  const [opacity, setOpacity] = useState(0);

  const handleMouseMove = useCallback((e: React.MouseEvent<HTMLDivElement>) => {
    if (!divRef.current) return;
    const { left, top } = divRef.current.getBoundingClientRect();
    set