magicui Documentation

Technical Documentation: magicuidesign/magicui

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Magic UI

Documentation Copy Chapter

Visit https://magicui.design/docs to view the documentation.

Contributing Copy Chapter

Visit our contributing guide to learn how to contribute. It only takes ~5 minutes to add your own!

Community Copy Chapter

Have questions, comments or feedback? Join our discord.

Authors Copy Chapter

Stats Copy Chapter

Star History Copy Chapter

License Copy Chapter

Licensed under the MIT license.

Apps Www Content Docs Index (`apps/www/content/docs/index.mdx`) Copy Section

title: Introduction Copy Chapter

Magic UI is a collection of re-usable components that you can copy and paste into your web apps.

It primarily features components, blocks, and templates geared towards creating landing pages and user-facing marketing materials.

Philosophy Copy Chapter

I personally believe that good design contributes significant value to software. It's one of the main methods of establishing trust between you and an internet stranger. Trust is important for internet businesses because it is the first thing a visitor evaluates before pulling out their credit card and becoming a customer.

Some questions visitors might ask themselves are:

• "Is this company legit?"
• "Who else is using it?"
• "Can I trust them with my personal data?"

Poor design reflects poorly on your team. It comes off as lazy, unfinished, and unstable. It shows that the team doesn't care about user experience.

Good design indicates that the team behind has their shit together. I can probably expect good things from them in the future.

It makes me think "if they care so much about these tiny details, they must care a lot about other things in the company, including their customers!".

A great example of this in play is https://linear.app landing page which I first came across in 2020. I didn't even need to try the product but I already knew that it must be good.

This library is heavily inspired by https://ui.shadcn.com.

Apps Www Content Docs Components Index (`apps/www/content/docs/components/index.mdx`) Copy Section

title: Components Copy Chapter

npx shadcn@latest init

npx shadcn@latest add @magicui/globe

import { Globe } from "@/components/ui/globe"

export default function Home() {
  return <Globe />
}

```bash
npx @magicuidesign/cli@latest install cursor
```

```bash
npx @magicuidesign/cli@latest install windsurf
```

```bash
npx @magicuidesign/cli@latest install claude
```

```bash
npx @magicuidesign/cli@latest install cline
```

```bash
npx @magicuidesign/cli@latest install roo-cline
```

{
  "mcpServers": {
    "magicuidesign-mcp": {
      "command": "npx",
      "args": ["-y", "@magicuidesign/mcp@latest"]
    }
  }
}

npx shadcn@latest add @magicui/android

import { Android } from "@/components/ui/android"

<Android />

npx shadcn@latest add @magicui/animated-beam

import { AnimatedBeam } from "@/components/ui/animated-beam"

<AnimatedBeam containerRef={containerRef} fromRef={fromRef} toRef={toRef} />

npx shadcn@latest add @magicui/animated-circular-progress-bar

import { AnimatedCircularProgressBar } from "@/components/ui/animated-circular-progress-bar"

<AnimatedCircularProgressBar />

npx shadcn@latest add @magicui/animated-gradient-text

@theme inline {
  --animate-gradient: gradient 8s linear infinite;

  @keyframes gradient {
    to {
      background-position: var(--bg-size, 300%) 0;
    }
  }
}

import { AnimatedGradientText } from "@/components/ui/animated-gradient-text"

<AnimatedGradientText>Animated Gradient Text</AnimatedGradientText>

npx shadcn@latest add @magicui/animated-grid-pattern

import { AnimatedGridPattern } from "@/components/ui/animated-grid-pattern"

<AnimatedGridPattern />

npx shadcn@latest add @magicui/animated-list

import { AnimatedList } from "@/components/ui/animated-list"

<AnimatedList>
  <p>Item 1</p>
  <p>Item 2</p>
  <p>Item 3</p>
</AnimatedList>

npx shadcn@latest add @magicui/animated-shiny-text

@theme inline {
  --animate-shiny-text: shiny-text 8s infinite;

  @keyframes shiny-text {
    0%,
    90%,
    100% {
      background-position: calc(-100% - var(--shiny-width)) 0;
    }
    30%,
    60% {
      background-position: calc(100% + var(--shiny-width)) 0;
    }
  }
}

import { AnimatedShinyText } from "@/components/ui/animated-shiny-text"

<AnimatedShinyText>Hello</AnimatedShinyText>

npx shadcn@latest add @magicui/animated-theme-toggler

::view-transition-old(root),
::view-transition-new(root) {
  animation: none;
  mix-blend-mode: normal;
}

/* Scoped to AnimatedThemeToggler — the toggler sets the data-attribute and the variable only during a theme toggle. */
html[data-magicui-theme-vt="active"]::view-transition-group(root) {
  animation-duration: var(--magicui-theme-toggle-vt-duration);
}

import { AnimatedThemeToggler } from "@/components/ui/animated-theme-toggler"

<AnimatedThemeToggler />

<AnimatedThemeToggler variant="star" />

<AnimatedThemeToggler variant="hexagon" duration={600} fromCenter />

npx shadcn@latest add @magicui/aurora-text

@theme inline {
  --animate-aurora: aurora 8s ease-in-out infinite alternate;

  @keyframes aurora {
    0% {
      background-position: 0% 50%;
      transform: rotate(-5deg) scale(0.9);
    }
    25% {
      background-position: 50% 100%;
      transform: rotate(5deg) scale(1.1);
    }
    50% {
      background-position: 100% 50%;
      transform: rotate(-3deg) scale(0.95);
    }
    75% {
      background-position: 50% 0%;
      transform: rotate(3deg) scale(1.05);
    }
    100% {
      background-position: 0% 50%;
      transform: rotate(-5deg) scale(0.9);
    }
  }
}

import { AuroraText } from "@/components/ui/aurora-text"

<AuroraText>Aurora Text</AuroraText>

npx shadcn@latest add @magicui/avatar-circles

import { AvatarCircles } from "@/components/ui/avatar-circles"

<AvatarCircles
  numPeople={99}
  avatarUrls={[
    {
      imageUrl: "https://avatars.githubusercontent.com/u/16860528",
      profileUrl: "https://github.com/dillionverma",
    },
  ]}
/>

npx shadcn@latest add @magicui/backlight

import { Backlight } from "@/components/ui/backlight"

<Backlight>
  <img src="https://some-url/image.png" />
</Backlight>

npx shadcn@latest add @magicui/bento-grid

import { BentoCard, BentoGrid } from "@/components/ui/bento-grid"

<BentoGrid>
  <BentoCard />
</BentoGrid>

npx shadcn@latest add @magicui/blur-fade

import { BlurFade } from "@/components/ui/blur-fade"

<BlurFade>
  <img src="https://picsum.photos/300/200?random=1" alt="Sample 1" />
  <img src="https://picsum.photos/300/200?random=2" alt="Sample 2" />
  <img src="https://picsum.photos/300/200?random=3" alt="Sample 3" />
</BlurFade>

npx shadcn@latest add @magicui/border-beam

import { BorderBeam } from "@/components/ui/border-beam"

<div className="relative h-[500px] w-full overflow-hidden">
  <BorderBeam />
</div>

npx shadcn@latest add @magicui/code-comparison

import { CodeComparison } from "@/components/ui/code-comparison"

<CodeComparison beforeCode={beforeCode} afterCode={afterCode} />

npx shadcn@latest add @magicui/comic-text

import { ComicText } from "@/components/ui/comic-text"

<ComicText>Comic Text</ComicText>

npx shadcn@latest add @magicui/confetti

npm install canvas-confetti

import { useRef } from "react"

import { Confetti, type ConfettiRef } from "@/components/ui/confetti"

export function ConfettiDemo() {
  const confettiRef = useRef<ConfettiRef>(null)

  return (
    <div>
      <Confetti ref={confettiRef} manualstart />
      <button onClick={() => confettiRef.current?.fire()}>
        Trigger Confetti
      </button>
    </div>
  )
}

npx shadcn@latest add @magicui/cool-mode

import { CoolMode } from "@/components/ui/cool-mode"

<CoolMode>
  <button>Click me</button>
</CoolMode>

npx shadcn@latest add @magicui/dia-text-reveal

import { DiaTextReveal } from "@/components/ui/dia-text-reveal"

<DiaTextReveal text="Magic UI" />

<h1 className="text-3xl font-semibold">
  Learn to{" "}
  <DiaTextReveal
    repeat
    repeatDelay={1.2}
    text={["build faster", "ship smarter", "scale easier"]}
  />
</h1>

npx shadcn@latest add @magicui/dock

import { Home, Search, Settings } from "lucide-react"

import { Dock, DockIcon } from "@/components/ui/dock"

<Dock>
  <DockIcon>
    <Home />
  </DockIcon>
  <DockIcon>
    <Settings />
  </DockIcon>
  <DockIcon>
    <Search />
  </DockIcon>
</Dock>

npx shadcn@latest add @magicui/dot-pattern

import { DotPattern } from "@/components/ui/dot-pattern"

<div className="relative h-[500px] w-full overflow-hidden">
  <DotPattern />
</div>

npx shadcn@latest add @magicui/dotted-map

import { DottedMap, type Marker } from "@/components/ui/dotted-map"

<div className="relative h-[400px] w-full overflow-hidden rounded-xl border">
  <DottedMap />
</div>

import { DottedMap, type Marker } from "@/components/ui/dotted-map"
import type { TCountryCode } from "countries-list"

type CountryCode = Lowercase<TCountryCode>

type MyMarker = Marker & {
  overlay: {
    countryCode: CountryCode
    label: string
  }
}

const markers: MyMarker[] = [
  {
    lat: 37.5665,
    lng: 126.978,
    size: 2.8,
    overlay: { countryCode: "kr", label: "Seoul" },
  },
]

<DottedMap<MyMarker>
  markers={markers}
  renderMarkerOverlay={({ marker, x, y, r }) => {
    // Custom overlay rendering
    return <text x={x} y={y}>{marker.overlay.label}</text>
  }}
/>

export interface Marker {
  lat: number
  lng: number
  size?: number
  pulse?: boolean
}

import type { TCountryCode } from "countries-list"

type CountryCode = Lowercase<TCountryCode>

type MyMarker = Marker & {
  overlay: {
    countryCode: CountryCode
    label: string
  }
}
;<DottedMap<MyMarker> markers={markers} />

npx shadcn@latest add @magicui/file-tree

import { Tree } from "@/components/ui/file-tree"
import type { TreeViewElement } from "@/components/ui/file-tree"

const elements: TreeViewElement[] = [
  {
    id: "src",
    type: "folder",
    name: "src",
    children: [
      { id: "components", type: "folder", name: "components" },
      { id: "app", type: "folder", name: "app" },
      { id: "page", name: "page.tsx" },
      { id: "layout", name: "layout.tsx" },
    ],
  },
]

<Tree elements={elements} />

npx shadcn@latest add @magicui/flickering-grid

import { FlickeringGrid } from "@/components/ui/flickering-grid"

<FlickeringGrid />

npx shadcn@latest add @magicui/floating-3d-particles

import { Floating3DParticles } from "@/components/ui/floating-3d-particles"

<div className="relative flex h-[500px] w-full items-center justify-center overflow-hidden rounded-lg border">
  <Floating3DParticles color="#8B5CF6" quantity={400} />
  <div className="relative z-10 text-center">
    <h2 className="text-3xl font-bold">Build Something Magical</h2>
  </div>
</div>

npx shadcn@latest add @magicui/glare-hover

import { GlareHover } from "@/registry/magicui/glare-hover"

<GlareHover className="rounded-lg">
  <Card>
    <CardContent>
      <CardTitle>Hello World</CardTitle>
      <CardDescription>Hover to see the glare sweep</CardDescription>
    </CardContent>
  </Card>
</GlareHover>

<GlareHover
  className="rounded-lg"
  color="#a78bfa"
  opacity={0.35}
  background="#0a0a0a"
>
  <Card>{/* ... */}</Card>
</GlareHover>

<GlareHover className="rounded-lg" angle={-30} size={280}>
  <Card>{/* ... */}</Card>
</GlareHover>

<GlareHover className="rounded-lg" duration={500}>
  <Card>{/* ... */}</Card>
</GlareHover>

<GlareHover className="rounded-lg" playOnce>
  <Card>{/* ... */}</Card>
</GlareHover>

npx shadcn@latest add @magicui/globe

npm install [email protected] motion

import { Globe } from "@/components/ui/globe"

<Globe />

npx shadcn@latest add @magicui/glyph-matrix

import { GlyphMatrix } from "@/registry/magicui/glyph-matrix"

<div className="border-border bg-background h-[400px] w-full overflow-hidden rounded-lg border">
  <GlyphMatrix />
</div>

npx shadcn@latest add @magicui/grid-pattern

import { GridPattern } from "@/components/ui/grid-pattern"

<div className="relative h-[500px] w-full overflow-hidden">
  <GridPattern />
</div>

npx shadcn@latest add @magicui/hero-video-dialog

import { HeroVideoDialog } from "@/components/ui/hero-video-dialog"

<HeroVideoDialog
  className="block dark:hidden"
  animationStyle="from-center"
  videoSrc="https://www.example.com/dummy-video"
  thumbnailSrc="https://www.example.com/dummy-thumbnail.png"
  thumbnailAlt="Dummy Video Thumbnail"
/>

npx shadcn@latest add @magicui/hexagon-pattern

import { HexagonPattern } from "@/components/ui/hexagon-pattern"

<div className="relative h-[500px] w-full overflow-hidden">
  <HexagonPattern />
</div>

npx shadcn@latest add @magicui/highlighter

pnpm add motion rough-notation

import { Highlighter } from "@/components/ui/highlighter"

<p>
  The{" "}
  <Highlighter action="underline" color="#FF9800">
    Magic UI Highlighter
  </Highlighter>{" "}
  makes important{" "}
  <Highlighter action="highlight" color="#87CEFA">
    text stand out
  </Highlighter>{" "}
  effortlessly.
</p>

npx shadcn@latest add @magicui/hyper-text

npm install motion

import { HyperText } from "@/components/ui/hyper-text"

<HyperText>Hover me</HyperText>

npx shadcn@latest add @magicui/icon-cloud

import { IconCloud } from "@/components/ui/icon-cloud"

<div className="relative overflow-hidden">
  <IconCloud images={images} />
</div>

npx shadcn@latest add @magicui/interactive-grid-pattern

import { InteractiveGridPattern } from "@/components/ui/interactive-grid-pattern"

<div className="relative h-[500px] w-full overflow-hidden">
  <InteractiveGridPattern />
</div>

npx shadcn@latest add @magicui/interactive-hover-button

import { InteractiveHoverButton } from "@/components/ui/interactive-hover-button"

<InteractiveHoverButton>Interactive Hover Button</InteractiveHoverButton>

npx shadcn@latest add @magicui/iphone

import { Iphone } from "@/components/ui/iphone"

<Iphone />

npx shadcn@latest add @magicui/kinetic-text

import { KineticText } from "@/components/ui/kinetic-text"

<KineticText text="some text" />

npx shadcn@latest add @magicui/lens

import { Lens } from "@/components/ui/lens"

<Lens>
  <img src="/images/lens-demo.jpg" alt="Lens Demo" />
</Lens>

npx shadcn@latest add @magicui/light-rays

import { LightRays } from "@/components/ui/light-rays"

<div className="relative h-[400px] w-full overflow-hidden rounded-xl border">
  <LightRays />
</div>

npx shadcn@latest add @magicui/line-shadow-text

@theme inline {
  --animate-line-shadow: line-shadow 15s linear infinite;

  @keyframes line-shadow {
    0% {
      background-position: 0 0;
    }
    100% {
      background-position: 100% -100%;
    }
  }
}

import { LineShadowText } from "@/components/ui/line-shadow-text"

<LineShadowText>Magic UI</LineShadowText>

npx shadcn@latest add @magicui/magic-card

import { MagicCard } from "@/components/ui/magic-card"

<MagicCard>
  <div className="p-4">
    <p>Hello World</p>
    <span>Hover me</span>
  </div>
</MagicCard>

npx shadcn@latest add @magicui/marquee

@theme inline {
  --animate-marquee: marquee var(--duration) infinite linear;
  --animate-marquee-vertical: marquee-vertical var(--duration) linear infinite;

  @keyframes marquee {
    from {
      transform: translateX(0);
    }
    to {
      transform: translateX(calc(-100% - var(--gap)));
    }
  }
  @keyframes marquee-vertical {
    from {
      transform: translateY(0);
    }
    to {
      transform: translateY(calc(-100% - var(--gap)));
    }
  }
}

import { Marquee } from "@/components/ui/marquee"

<Marquee>
  <span>Next.js</span>
  <span>React</span>
  <span>TypeScript</span>
  <span>Tailwind CSS</span>
</Marquee>

npx shadcn@latest add @magicui/meteors

@theme inline {
  --animate-meteor: meteor 5s linear infinite;

  @keyframes meteor {
    0% {
      transform: rotate(var(--angle)) translateX(0);
      opacity: 1;
    }
    70% {
      opacity: 1;
    }
    100% {
      transform: rotate(var(--angle)) translateX(-500px);
      opacity: 0;
    }
  }
}

import { Meteors } from "@/components/ui/meteors"

<div className="relative h-[500px] w-full overflow-hidden">
  <Meteors />
</div>

npx shadcn@latest add @magicui/morphing-text

import { MorphingText } from "@/components/ui/morphing-text"

<MorphingText texts={["Hello", "World"]} />

npx shadcn@latest add @magicui/neon-gradient-card

@theme inline {
  --animate-background-position-spin: background-position-spin 3000ms infinite
    alternate;

  @keyframes background-position-spin {
    0% {
      background-position: top center;
    }
    100% {
      background-position: bottom center;
    }
  }
}

import { NeonGradientCard } from "@/components/ui/neon-gradient-card"

<NeonGradientCard>
  <div className="p-4">
    <p>Hello</p>
    <span>Hover me</span>
  </div>
</NeonGradientCard>

npx shadcn@latest add @magicui/noise-texture

import { NoiseTexture } from "@/components/ui/noise-texture"

<div className="relative h-64 overflow-hidden rounded-lg border">
  <NoiseTexture />
</div>

npx shadcn@latest add @magicui/number-ticker

import { NumberTicker } from "@/components/ui/number-ticker"

<NumberTicker value={100} />

npx shadcn@latest add @magicui/orbiting-circles

@theme inline {
  --animate-orbit: orbit calc(var(--duration) * 1s) linear infinite;

  @keyframes orbit {
    0% {
      transform: rotate(calc(var(--angle) * 1deg))
        translateY(calc(var(--radius) * 1px)) rotate(calc(var(--angle) * -1deg));
    }
    100% {
      transform: rotate(calc(var(--angle) * 1deg + 360deg))
        translateY(calc(var(--radius) * 1px))
        rotate(calc((var(--angle) * -1deg) - 360deg));
    }
  }
}

import { File, Search, Settings } from "lucide-react"

import { OrbitingCircles } from "@/components/ui/orbiting-circles"

<div className="relative h-[500px] w-full overflow-hidden">
  <OrbitingCircles>
    <File />
    <Settings />
    <File />
  </OrbitingCircles>
  <OrbitingCircles radius={100} reverse>
    <File />
    <Settings />
    <File />
    <Search />
  </OrbitingCircles>
</div>

npx shadcn@latest add @magicui/particles

import { Particles } from "@/components/ui/particles"

<div className="relative h-[500px] w-full overflow-hidden">
  <Particles />
</div>

npx shadcn@latest add @magicui/pixel-image

import { PixelImage } from "@/components/ui/pixel-image"

<PixelImage src="/pixel-image-demo.jpg" grid="8x8" />

// Predefined grid options
"6x4" | "8x8" | "8x3" | "4x6" | "3x8"

// Custom grid example
customGrid={{ rows: 5, cols: 10 }}

npx shadcn@latest add @magicui/pointer

import { Pointer } from "@/components/ui/pointer"

<Pointer />

npx shadcn@latest add @magicui/progressive-blur

import { ProgressiveBlur } from "@/components/ui/progressive-blur"

<div className="relative h-[400px] w-full overflow-auto">
  {/* Your scrollable content */}
  <div className="space-y-4 p-4">{/* Content items */}</div>

  <ProgressiveBlur height="50%" position="bottom" />
</div>

npx shadcn@latest add @magicui/pulsating-button

@theme inline {
  --animate-pulse: pulse var(--duration) ease-out infinite;
  --animate-pulse-ripple: pulse-ripple var(--duration)
    cubic-bezier(0.16, 1, 0.3, 1) infinite;

  @keyframes pulse {
    0%,
    100% {
      box-shadow: 0 0 0 0 var(--pulse-color, oklch(from var(--bg) l c h / 0.5));
    }
    50% {
      box-shadow: 0 0 0 var(--distance)
        var(--pulse-color, oklch(from var(--bg) l c h / 0.5));
    }
  }

  @keyframes pulse-ripple {
    0% {
      box-shadow: 0 0 0 0 oklch(from var(--pulse-color, var(--bg)) l c h / 1);
    }
    100% {
      box-shadow: 0 0 0 var(--distance)
        oklch(from var(--pulse-color, var(--bg)) l c h / 0);
    }
  }
}

import { PulsatingButton } from "@/components/ui/pulsating-button"

<PulsatingButton>Pulsating Button</PulsatingButton>