Confetti `<mv-confetti-button>`

물리 기반 캔버스 색종이(중력, 공기 저항, 3D 회전, 흔들림): 독립 실행형 confetti() 함수, 대포 / 불꽃놀이 / 별 / 이모지 프리셋, 트리거 버튼, 길게 누르는 “cool” 모드를 제공합니다.

카테고리	마이크로 인터랙션
유형	Web Component (`<mv-confetti-button>`)
상태	안정
Keywords	confetti, celebration, canvas, particles, emoji, cool-mode, success

When to use

A purchase, signup or completed milestone deserves a celebratory confetti burst
A launch or achievement screen needs cannons, fireworks, stars or emoji raining across the screen
A playful press-and-hold stream of particles should follow the pointer on a button

Avoid when

The feedback is a small click acknowledgment rather than a celebration → use Click Spark instead
Users need to know the outcome of the action; announce it with text → use Toast instead
The action is routine and frequent; repeated celebrations quickly feel noisy

설치

node scripts/add.mjs confetti --out ./src/marvelous

Marvelous UI MCP 서버를 사용하는 AI 에이전트: install_components({ slugs: ["confetti"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).

복사되는 파일(의존성 포함): tokens/tokens.css, core/base.css, core/canvas.js, core/element.js, core/motion.js, components/confetti/confetti.js.

사용법

기본 마크업입니다. 여기서 시작해 속성, data-*, CSS 변수로 커스터마이즈하세요:

<div style="display:grid;gap:1.25rem;justify-items:center;text-align:center">
  <div style="display:grid;gap:.35rem">
    <strong style="font-size:1.05rem">Payment confirmed. Thanks, Priya!</strong>
    <span style="color:var(--mv-fg-muted);font-size:.85rem">Order #48213 · arriving Thursday</span>
  </div>
  <div style="display:flex;flex-wrap:wrap;gap:.75rem;justify-content:center">
    <mv-confetti-button>
      <button class="mv-button" data-shape="pill">🎉 Celebrate</button>
    </mv-confetti-button>
    <mv-confetti-button preset="stars">
      <button class="mv-button" data-variant="secondary" data-shape="pill">Stars</button>
    </mv-confetti-button>
    <mv-confetti-button emoji="🥯,☕,🥞" scalar="1.3" count="36" spread="100">
      <button class="mv-button" data-variant="outline" data-shape="pill">Free breakfast</button>
    </mv-confetti-button>
    <mv-confetti-button preset="cannons">
      <button class="mv-button" data-variant="outline" data-shape="pill">Cannons</button>
    </mv-confetti-button>
    <mv-confetti-button preset="fireworks">
      <button class="mv-button" data-variant="outline" data-shape="pill">Fireworks</button>
    </mv-confetti-button>
  </div>
  <div style="display:flex;flex-wrap:wrap;gap:.75rem;justify-content:center;align-items:center">
    <mv-confetti-button preset="cool" emoji="💜,✨">
      <button class="mv-button" data-variant="ghost">Hold for a shower of hearts</button>
    </mv-confetti-button>
    <button class="mv-button" data-variant="ghost" data-mv-confetti data-confetti-shapes="circle" data-confetti-colors="var(--mv-accent),var(--mv-success)">data-mv-confetti</button>
  </div>
</div>

API

Attributes

Name	유형	Default	Description
`preset`	burst \| stars \| cannons \| fireworks \| cool	`burst`	burst/stars fire from the clicked button; cannons/fireworks cover the screen; cool = continuous stream while the pointer is held.
`count`	number	`80`	Confetti pieces per burst.
`spread / angle`	degrees	`70 / 90`	Cone width and direction (90 = straight up).
`velocity / gravity / scalar`	number	`42 / 0.55 / 1`	Initial velocity, gravity, size.
`colors`	comma-separated list of CSS colors		Colors (tokens accepted). Default: accent + a festive palette.
`shapes`	square,circle,star	`square,square,circle`	Shapes picked at random.
`emoji`	comma-separated list		Replaces shapes with emoji/text (rasterized once).
`disabled`	boolean		Stops firing.
`data-mv-confetti`	preset (on any element)		Declarative trigger without a wrapper; options via data-confetti-count, -spread, -angle, -velocity, -gravity, -scalar, -colors, -shapes, -emoji.

Methods

Name	Description
`confetti(options)`	Export: { particleCount, angle, spread, startVelocity, decay, gravity, drift, ticks, scalar, origin: {x,y} (0..1 viewport) \| element, colors, shapes, emoji, flat, respectMotion }. Returns a Promise that resolves once everything has landed.
`confetti.cannons / .fireworks / .stars (options)`	Presets; cannons and fireworks accept duration (ms).
`confetti.reset()`	Clears everything immediately.
`coolMode(el, options)`	Export: streams particles under the pointer while it is held on el; returns a cleanup function.
`fire(from?)`	`<mv-confetti-button>` method: fires the preset from an element.

Events

Name	Description
`mv-fire`	On every `<mv-confetti-button>` shot; detail = { preset }.

Content structure

Name	Description
`(child)`	The trigger button or link (stays a real `<button>`).

Accessibility

Decorative: a single aria-hidden canvas, pointer-events: none, placed in the top layer (above modals) and removed from the DOM as soon as the last piece has landed. No rAF loop when idle. Reduced motion: no confetti (the promise resolves immediately) and the button keeps its normal feedback; force it with respectMotion: false. The child button keeps its accessible name; announce the success itself with text or a live region.