magicui

name	magicui
description	Installs Magic UI animated React components through magicui-cli into a Tailwind + shadcn tree (marquee, shimmer-button, number-ticker, animated-beam). Trigger on magicui/magic-ui landing kits or those registry names. Do not use for stock shadcn primitives, Emil-style popover craft, or Remotion frame animation.
version	1.0.1

Magic UI

Overview

Magic UI is a collection of animated React components built on Tailwind CSS and shadcn/ui. Components are installed via CLI directly into your project — you own the source code and can customize freely.

Key traits:

• CLI-based install (no runtime package dependency)
• Tailwind CSS + CSS variables for theming
• shadcn/ui compatible
• TypeScript first
• React 18+ (works with 19), Tailwind 3+ (works with v4)

When to Use

Use this skill when the user:

• Explicitly asks for magicui or Magic UI components
• Needs animated React UI components (marquees, counters, shimmer buttons, ripple backgrounds, meteors, confetti, etc.)
• Is building a landing page, hero section, or marketing page with motion effects
• Wants to install, customize, or troubleshoot Magic UI components
• Needs frontend UI/UX guidance for React + Tailwind + shadcn/ui projects
• Asks about responsive layout, accessibility, component states, or design-system integration with Magic UI

Prerequisites

Before installing Magic UI components, ensure the project has Tailwind CSS and shadcn/ui configured.

1. Install Tailwind CSS (if not present)

npm install tailwindcss @tailwindcss/typography

2. Initialize shadcn/ui (if not present)

npx shadcn@latest init

This sets up the cn utility in lib/utils.ts (requires clsx + tailwind-merge).

3. Verify cn utility exists

# Check for the utility file
cat lib/utils.ts

If missing, create lib/utils.ts:

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

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

Install dependencies if needed:

npm install clsx tailwind-merge

Procedure

Install a Component

npx magicui-cli add <component-name>

This copies the component source into components/magicui/. You own the code and can edit it freely.

Windows (PowerShell): If npx prompts to install, confirm with y. Use npx magicui-cli@latest if you hit a "component not found" error.

List All Available Components

npx magicui-cli list

Popular Component Catalog

animated-beam, animated-gradient-text, animated-grid-pattern, animated-list, animated-shiny-text, aurora-text, blur-in, blur-fade, border-beam, confetti, cool-mode, dock, dot-pattern, file-tree, flip-text, globe, grid-pattern, hyper-text, interactive-hover-button, letter-pullup, magic-card, marquee, meteors, morphing-text, neon-gradient-card, number-ticker, orbiting-circles, particles, pointer, pulsating-button, rainbow-button, retro-grid, ripple, safari, scroll-based-velocity, shimmer-button, shine-border, shiny-button, sparkles-text, spinning-text, terminal, text-reveal, ticker, typing-animation, vanish-input, wavy-text, word-fade-in, word-pull-up, word-rotate

Component Examples

AnimatedBeam — connecting lines between elements

npx magicui-cli add animated-beam

import { AnimatedBeam } from "@/components/magicui/animated-beam";
import { useRef } from "react";

export function BeamDemo() {
  const containerRef = useRef<HTMLDivElement>(null);
  const fromRef = useRef<HTMLDivElement>(null);
  const toRef = useRef<HTMLDivElement>(null);

  return (
    <div ref={containerRef} className="relative flex h-64 items-center justify-between p-10">
      <div ref={fromRef} className="h-12 w-12 rounded-full bg-blue-500" />
      <div ref={toRef} className="h-12 w-12 rounded-full bg-purple-500" />
      <AnimatedBeam containerRef={containerRef} fromRef={fromRef} toRef={toRef} />
    </div>
  );
}

Marquee — infinite scrolling ticker

npx magicui-cli add marquee

import Marquee from "@/components/magicui/marquee";

const logos = ["Vercel", "Stripe", "Linear", "Notion", "Figma"];

export function LogoMarquee() {
  return (
    <Marquee pauseOnHover className="[--duration:20s]">
      {logos.map((name) => (
        <div key={name} className="mx-8 text-xl font-semibold text-muted-foreground">
          {name}
        </div>
      ))}
    </Marquee>
  );
}

ShimmerButton — animated gradient CTA

npx magicui-cli add shimmer-button

import { ShimmerButton } from "@/components/magicui/shimmer-button";

export function HeroCTA() {
  return (
    <ShimmerButton
      shimmerColor="#ffffff"
      shimmerSize="0.1em"
      shimmerDuration="2s"
      background="linear-gradient(135deg, #6366f1, #8b5cf6)"
      className="px-8 py-3 text-white font-semibold"
    >
      Get Started Free
    </ShimmerButton>
  );
}

NumberTicker — animated counting up

npx magicui-cli add number-ticker

import NumberTicker from "@/components/magicui/number-ticker";

export function StatsSection() {
  return (
    <div className="grid grid-cols-3 gap-8 text-center">
      <div>
        <NumberTicker value={10000} className="text-5xl font-bold" />
        <p className="text-muted-foreground">Active Users</p>
      </div>
      <div>
        <NumberTicker value={99} className="text-5xl font-bold" />
        <span className="text-5xl font-bold">%</span>
        <p className="text-muted-foreground">Uptime</p>
      </div>
      <div>
        <NumberTicker value={500} className= />
        Customers
      
    
  );
}

SparklesText — glittering highlight text

npx magicui-cli add sparkles-text

import SparklesText from "@/components/magicui/sparkles-text";

export function HeroHeading() {
  return (
    <h1 className="text-6xl font-bold">
      Build{" "}
      <SparklesText text="faster" colors={{ first: "#6366f1", second: "#ec4899" }} />
      {" "}with AI
    </h1>
  );
}

Ripple — pulsing circle effect

npx magicui-cli add ripple

import { Ripple } from "@/components/magicui/ripple";

export function HeroBackground() {
  return (
    <div className="relative flex h-96 items-center justify-center overflow-hidden bg-background">
      <Ripple mainCircleSize={200} numCircles={8} />
      <p className="z-10 text-4xl font-bold">Connect Everything</p>
    </div>
  );
}

Confetti — celebration burst

npx magicui-cli add confetti

import { useConfetti } from "@/components/magicui/confetti";

export function SuccessButton() {
  const { fire } = useConfetti();

  return (
    <button
      onClick={() => fire({ particleCount: 100, spread: 70, origin: { y: 0.6 } })}
      className="rounded-lg bg-green-500 px-6 py-3 text-white font-semibold"
    >
      Complete Purchase
    </button>
  );
}

Meteors — falling meteor streaks background

npx magicui-cli add meteors

import { Meteors } from "@/components/magicui/meteors";

export function HeroCard() {
  return (
    <div className="relative overflow-hidden rounded-2xl border bg-background p-8">
      <Meteors number={20} />
      <h2 className="relative z-10 text-3xl font-bold">Your Product Name</h2>
      <p className="relative z-10 mt-2 text-muted-foreground">Tagline goes here</p>
    </div>
  );
}

BlurIn — text fade-in with blur

npx magicui-cli add blur-in

import BlurIn from "@/components/magicui/blur-in";

export function AnimatedHero() {
  return (
    <BlurIn
      word="The Future of Development"
      className="text-5xl font-bold tracking-tight"
      duration={1.2}
    />
  );
}

Globe — 3D interactive globe

npx magicui-cli add globe

import Globe from "@/components/magicui/globe";

export function GlobalSection() {
  return (
    <div className="flex flex-col items-center">
      <h2 className="text-3xl font-bold">Available Worldwide</h2>
      <Globe className="h-[500px] w-[500px]" />
    </div>
  );
}

Full Landing Page Pattern

// app/page.tsx — typical hero section with Magic UI components
import BlurIn from "@/components/magicui/blur-in";
import { ShimmerButton } from "@/components/magicui/shimmer-button";
import { Ripple } from "@/components/magicui/ripple";
import Marquee from "@/components/magicui/marquee";
import NumberTicker from "@/components/magicui/number-ticker";

export default function LandingPage() {
  return (
    <main>
      {/* Hero */}
      <section className="relative flex h-screen flex-col items-center justify-center text-center">
        <Ripple mainCircleSize={300} numCircles={6} />
        <BlurIn word="Ship Faster Than Ever" className="z-10 text-6xl font-bold" />
        <p className="z-10 mt-4 text-xl text-muted-foreground">
          The platform that gets you from idea to production
        </p>
        Start for free
      

      {/* Social proof logos */}
      
        
          {["Company A", "Company B", "Company C", "Company D", "Company E"].map((name) => (
            {name}
          ))}
        
      

      {/* Stats */}
      
        
          Users
          %Uptime
          +Countries
        
      
    
  );
}

UI/UX Design Workflow

When the user asks for design or implementation guidance (not just component installation):

1. Start from the user task and information architecture, not decoration.
2. Map key states: empty, loading, success, error, disabled, permission-limited, offline, and responsive variants.
3. Apply accessibility requirements early: keyboard flow, focus visibility, labels, contrast, reduced motion, touch targets, text resizing, and semantic structure.
4. Use design-system primitives where available; otherwise define tokens for spacing, color, type, elevation, radius, and motion.
5. Design responsive layouts with stable dimensions and no text overlap across desktop and mobile.
6. Validate with realistic content: long labels, error text, touch/keyboard interaction.
7. Deliver concrete implementation guidance, not vague aesthetic notes.

Output format for design tasks: Return a plan with user goal, layout structure, component list, states, accessibility checks, responsive behavior, copy notes, and verification steps. For code tasks, include exact files/components and testing guidance.

Pitfalls

Issue	Fix
cn not found	Install clsx + tailwind-merge and add lib/utils.ts (see Prerequisites)
Animation not working (Tailwind v4)	Define keyframes/CSS vars in your CSS via @theme and add the dark variant with @custom-variant dark (&:where(.dark, .dark *))
Animation not working (Tailwind v3)	Ensure tailwind.config.ts has darkMode: "class" plus the animation keyframes in the theme.extend.keyframes and theme.extend.animation sections
Component not found	Run npx magicui-cli@latest add <name> (use @latest to get the current registry)
Peer dep warnings	Magic UI needs React 18+ (works with 19) and Tailwind 3+ (works with v4). Update if on older versions
Motion causes vestibular issues	Wrap animations in prefers-reduced-motion checks; provide static fallbacks for users with reduced motion enabled
Text overlap on mobile	Avoid fragile viewport-scaled text; use responsive font classes (text-sm md:text-lg) instead of vw units
Layout shift on state change	Reserve space for loading/error states with fixed dimensions or skeletons

Verification

After installing and using Magic UI components, verify:

1. Component file exists

# Check the installed component
ls components/magicui/<component-name>.tsx

2. Dev server compiles without errors

npm run dev

Open the page using the component — confirm no TypeScript or import errors in the terminal or browser console.

3. Accessibility checks

• Tab through the page: all interactive elements are keyboard-reachable with visible focus
• Run a screen reader pass: semantic headings and labels are announced correctly
• Check contrast ratios meet WCAG 2.2 AA (4.5:1 for normal text, 3:1 for large text)
• Enable prefers-reduced-motion in OS settings: animations should degrade gracefully

4. Responsive checks

• Test at 375px (mobile), 768px (tablet), 1280px (desktop) widths
• Confirm no text overlap, no horizontal scroll, no layout shift
• Verify touch targets are at least 44×44px on mobile

5. Dark/light mode

• Toggle between light and dark themes
• Confirm CSS variables resolve correctly in both modes

Quality Checklist

• User can complete the core task quickly and repeatedly
• UI supports keyboard, screen readers, visible focus, and sufficient contrast
• Mobile and desktop layouts do not overlap or rely on fragile viewport-scaled text
• Controls use familiar affordances and expose state clearly
• Motion is purposeful and respects prefers-reduced-motion
• Visual direction is intentional and consistent with the product domain
• All component states implemented: empty, loading, success, error, disabled
• Styling follows the app's existing design system — no ornamental drift

Failure Handling

If requirements conflict, prioritize usability, accessibility, and product fit over novelty. If a requested visual pattern harms readability or accessibility, explain the tradeoff and offer a better variant. Verify current platform guidance when building for Apple, Android, or a specific design system.

References

• W3C WCAG 2.2: https://www.w3.org/TR/WCAG22/
• W3C Understanding WCAG 2.2: https://www.w3.org/WAI/WCAG22/Understanding/intro
• W3C WCAG FAQ: https://www.w3.org/WAI/standards-guidelines/wcag/faq/
• Apple Human Interface Guidelines: https://developer.apple.com/design/human-interface-guidelines
• Material accessibility guidance: https://m2.material.io/design/usability/accessibility.html

Re-check official/current docs before relying on provider-specific APIs, policy, pricing, security behavior, or platform rules. Sources verified 2026-05-31.