部分上游示例使用在线图片、视频或推文；这些内容依赖网络与第三方服务，不代表本地预览加载失败。

彩纸庆祝

Magic UI 的独立组件，请不要替换为 JGuang UI/Base UI 的同名 API。

安装

npx shadcn@latest add https://jiguang132.com/r/magic-ui/confetti.json

Registry 将复制可编辑源码和依赖到独立命名空间。检查主题变量与 Tailwind CSS v4 配置；不要覆盖已有的项目组件。

使用与验证

在左侧选择组件，在预览中操作它的状态；使用“查看代码”检查真实源码。安装后执行类型检查和构建，再验证键盘焦点、手机布局与深浅色主题。

来源

https://github.com/magicuidesign/magicui/tree/cdb348cb4c72a9b54b554d8617801e479fbc8714 MIT 许可证；不包括付费内容。下方提供上游英文参考内容，中文使用指南已适配；上游详细参考暂保留英文。

适用场景

通过 ref 或按钮发射 Canvas 彩纸。

示例使用的原生参数

从该组件全部本地示例的 JSX 提取，按导入模块及组件区分；包括复合示例中实际使用的其他 Magic UI 组件。不是全部属性清单，也不是宿主通用 variant API。展开对象需结合示例数据声明；完整类型与默认值见下方源码参考。

所属组件参数	说明	示例来源
`Confetti.ref` (confetti)	指向原生命令式 API 或 DOM 目标的 React 引用，不是业务值。	`examples/confetti-demo.tsx`
`Confetti.className` (confetti)	当前原生组件的样式类，需先配置 Tailwind 与所需 CSS。	`examples/confetti-demo.tsx`
`Confetti.onMouseEnter` (confetti)	示例中的原生悬停处理函数，通常调用彩纸 ref。	`examples/confetti-demo.tsx`
`ConfettiButton.children` (confetti)	原生子内容，保留所属组件对文本/元素的约束。	`examples/confetti-basic-cannon.tsx`、`examples/confetti-random-direction.tsx`
`ConfettiButton.options` (confetti)	原生 canvas-confetti 配置/全局配置。	`examples/confetti-random-direction.tsx`

交互与状态检查

彩纸庆祝 · 默认示例 — confetti-demo
彩纸庆祝 · 基础喷射 — confetti-basic-cannon
彩纸庆祝 · 随机方向 — confetti-random-direction
彩纸庆祝 · 烟花 — confetti-fireworks
彩纸庆祝 · 星形彩纸 — confetti-stars
彩纸庆祝 · 两侧喷射 — confetti-side-cannons
彩纸庆祝 · 自定义形状 — confetti-custom-shapes
彩纸庆祝 · 表情彩纸 — confetti-emoji

这些名称是实际示例入口，不是新增组件属性或独立组件数量。选择对应示例后，检查指针/键盘行为、深浅色、手机尺寸和加载失败；纯装饰特效不应伪造禁用、错误或提交状态。完整示例安装包含其真实依赖闭包。

业务接入边界

Confetti 与 ConfettiButton API 不同；尊重减少动画并在退出时重置/销毁资源；庆祝动画不是交易成功证据。

宿主与动画配置

初始化 Tailwind CSS v4、语义 CSS 变量及 dark 变体；按本地 Registry 的独立命名空间导入。复用已有 next-themes Provider，不混入 JGuang UI/Base UI/HeroUI API。进入视口再挂载特效，离开后卸载；为 Canvas/WebGL 不可用、网络媒体失败提供静态替代。遵循 prefers-reduced-motion，并验证计时器、RAF、观察器和事件监听已清理；不能仅凭 CSS 停止就宣称引擎已停止。示例不提供后端、登录、支付或真实 AI 流。这里的实用指南为双语，上游详细参考和演示文本仍保留原文。

可用状态与示例

彩纸庆祝 · 默认示例、彩纸庆祝 · 基础喷射、彩纸庆祝 · 随机方向、彩纸庆祝 · 烟花、彩纸庆祝 · 星形彩纸、彩纸庆祝 · 两侧喷射、彩纸庆祝 · 自定义形状、彩纸庆祝 · 表情彩纸

组件中的状态与数据为演示用途，不包含后端接口。接入实际项目时请检查源码中的公开参数，再连接业务数据。

Installation

<Tabs defaultValue="cli"> <TabsList> <TabsTrigger value="cli">CLI</TabsTrigger> <TabsTrigger value="manual">Manual</TabsTrigger> </TabsList> <TabsContent value="cli">

npx shadcn@latest add @magicui/confetti

</TabsContent> <TabsContent value="manual"> <Steps>

<Step>Install the following dependencies:</Step>

npm install canvas-confetti

<Step>Copy and paste the following code into your project.</Step>

<Step>Update the import paths to match your project setup.</Step>

</Steps> </TabsContent> </Tabs>

Examples

Basic

Random Direction

Fireworks

Side Cannons

Stars

Custom Shapes

Emoji

Usage

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>
  )
}

Props

Confetti

Prop	Type	Default	Description
`ref`	`React.Ref<ConfettiRef>`	`null`	Ref exposing imperative `fire(options?: ConfettiOptions)` method
`options`	`ConfettiOptions`	`{}`	Default options for automatic or imperative confetti triggers
`globalOptions`	`ConfettiGlobalOptions`	`{ resize: true, useWorker: true }`	Global options passed to `canvas-confetti.create()`
`manualstart`	`Boolean`	`false`	Prevents automatic confetti firing on component mount
`className`	`String`	`undefined`	Custom CSS classes applied to the canvas element

ConfettiRef

Method	Parameters	Return Type	Description
`fire`	`options?: ConfettiOptions`	`Promise<void> \| void`	Imperatively triggers a confetti burst on the canvas instance

ConfettiOptions

Field	Type	Default	Description
`particleCount`	`Integer`	`50`	Number of confetti particles to launch
`angle`	`Number`	`90`	Launch angle in degrees
`spread`	`Number`	`45`	Spread angle in degrees
`startVelocity`	`Number`	`45`	Initial particle velocity
`decay`	`Number`	`0.9`	Velocity decay rate
`gravity`	`Number`	`1`	Gravity applied to particles
`drift`	`Number`	`0`	Horizontal drift factor
`flat`	`Boolean`	`false`	Renders flat 2D shapes
`ticks`	`Number`	`200`	Number of animation frames confetti lasts
`origin`	`{ x: number, y: number }`	`{ x: 0.5, y: 0.5 }`	Normalized viewport origin coordinates (`0.0` to `1.0`)
`colors`	`Array of Strings`	`HEX array`	Custom HEX color palette
`shapes`	`Array of Strings`	`['square', 'circle', 'star']`	Particle shapes or custom text shapes
`zIndex`	`Integer`	`9999`	Z-index of the confetti burst
`scalar`	`Number`	`1`	Scaling factor for particle dimensions

ConfettiButton

Prop	Type	Default	Description
`options`	`ConfettiOptions & ConfettiGlobalOptions`	`{}`	Options for the confetti launched on button click
`children`	`React.ReactNode`	`null`	Button label and child elements
`ref`	`React.Ref<HTMLButtonElement>`	`null`	Forwarded DOM reference to the underlying button

Credits

Credit to Bankk
Inspired by canvas-confetti

完整示例安装

组件安装命令只安装组件；下列示例命令还包含该示例实际导入的其他组件、原生辅助 UI、工具和固定版本依赖。辅助源码不算独立组件。