Aceternity UI

Overview

Aceternity UI is a copy-paste component library: there is no aceternity runtime package. Each component is a source file served from a shadcn-compatible registry at ui.aceternity.com/registry/<name>.json; the shadcn CLI writes it into components/ui/ and installs its dependencies, so you own and edit the code. Free components are installed this way; the site also sells a paid "Pro" set of templates and blocks, which is outside this skill.

Components are built with Tailwind CSS and, for most animation, the motion package (the successor of framer-motion; imports come from motion/react). Registry entries use the @/lib/utils cn helper, so a shadcn-initialised project is the easiest base.

Instructions

1. Prepare the project

npx shadcn@latest init          # creates components.json and lib/utils.ts (cn helper)

Register the namespace in components.json (needs shadcn CLI 3.x):

{
  "registries": {
    "@aceternity": "https://ui.aceternity.com/registry/{name}.json"
  }
}

2. Add components

npx shadcn@latest add @aceternity/3d-card
npx shadcn@latest add @aceternity/background-beams @aceternity/spotlight
npx shadcn@latest add https://ui.aceternity.com/registry/moving-border.json   # no namespace needed

npx shadcn@latest search @aceternity -q "card"   # find components
npx shadcn@latest list @aceternity               # list everything

In a monorepo add -c ./apps/web. npx shadcn@latest mcp init lets an AI agent search and install from the registry itself. Always read the installed file: registry code is updated over time, and the file you get is the source of truth for props.

3. Component notes (what the registry files export)

Component	Exports / key props	Extra dependency
3d-card	CardContainer, CardBody, CardItem (translateZ, rotateX, as)	none
background-beams	BackgroundBeams (absolute, fills parent)	motion
spotlight	Spotlight (SVG, props className, fill)	needs animate-spotlight in Tailwind
moving-border	Button (borderRadius, duration, as), MovingBorder	motion
wavy-background	WavyBackground (colors, backgroundFill, blur, speed: "slow" | "fast", waveOpacity)	simplex-noise
glowing-stars, lamp	decorative sections	motion

The spotlight component animates through a Tailwind animation you must define. Tailwind v3 (tailwind.config.ts):

extend: {
  animation: { spotlight: "spotlight 2s ease .75s 1 forwards" },
  keyframes: {
    spotlight: {
      "0%": { opacity: "0", transform: "translate(-72%, -62%) scale(0.5)" },
      "100%": { opacity: "1", transform: "translate(-50%, -40%) scale(1)" },
    },
  },
}

On Tailwind v4 put the same values in the CSS @theme block (--animate-spotlight plus an @keyframes spotlight rule).

Examples

Example 1: Hero with beams and a spotlight

User prompt: "Give the landing page a dark hero with animated beams and a spotlight."

npx shadcn@latest add @aceternity/background-beams @aceternity/spotlight

// app/page.tsx
import { BackgroundBeams } from "@/components/ui/background-beams";
import { Spotlight } from "@/components/ui/spotlight";

export default function Home() {
  return (
    <section className="relative flex h-screen flex-col items-center justify-center overflow-hidden bg-neutral-950">
      <Spotlight className="-top-40 left-0 md:left-60 md:-top-20" fill="white" />
      <BackgroundBeams />
      <h1 className="relative z-10 text-6xl font-bold text-white">Ship invoices in seconds</h1>
    </section>
  );
}

Result: beams animate behind the heading and the spotlight fades in once on load. Keep the text at z-10 so it stays above the absolute-positioned effects.

Example 2: Pricing card that tilts on hover

User prompt: "Make the Pro plan card tilt in 3D when the mouse moves over it."

npx shadcn@latest add @aceternity/3d-card

import { CardContainer, CardBody, CardItem } from "@/components/ui/3d-card";

export function ProPlan() {
  return (
    <CardContainer className="inter-var">
      <CardBody className="h-auto w-80 rounded-xl border border-white/10 bg-neutral-900 p-8">
        <CardItem translateZ="50" className="text-2xl font-bold text-white">Pro plan</CardItem>
        <CardItem translateZ="80" className="mt-4 text-4xl font-bold text-white">$29/mo</CardItem>
        <CardItem translateZ="40" as="button" className="mt-6 rounded-lg bg-white px-6 py-3 font-semibold text-black">
          Get started
        </CardItem>
      </CardBody>
    </CardContainer>
  );
}

Result: the card rotates toward the cursor and each CardItem floats at its own depth.

Guidelines

• Install through the CLI instead of retyping component code; hand-copied snippets drift from the registry.
• Components use "use client"; import them from client or server components in the Next.js App Router, but never call them from server-only code.
• They are dark-theme designs; check contrast in light mode.
• Canvas and SVG effects (wavy-background, beams) cost CPU/GPU. Load them with next/dynamic and ssr: false below the fold, and respect prefers-reduced-motion.
• wavy-background sizes its canvas to the window, so it suits full-width sections only.
• Do not stack many effects on one screen; one hero effect plus plain content reads better and scores better on Core Web Vitals.
• Older tutorials import from framer-motion; both packages work, but registry files now import from motion/react. Do not mix them without need.
• Check the license on the site before reusing Pro blocks commercially.