Particles `<mv-particles>`

떠다니며 반짝이는 Canvas 파티클로, 커서에 밀려나거나 끌려왔다가 탄력 있게 돌아갑니다. 선택적 별자리 모드는 이웃 파티클과 포인터를 선으로 잇습니다.

카테고리	배경
유형	Web Component (`<mv-particles>`)
상태	안정
Keywords	particles, sparkles, constellation, interactive, hero, canvas

When to use

A hero should respond to the cursor with drifting particles that scatter or gather
A network, AI or blockchain story fits a constellation of points linked to each other and the pointer
Ambient sparkle is wanted on a light or dark surface using the theme colors

Avoid when

Low-end mobile at high density with constellation links; a static CSS pattern is far cheaper → use Dot Pattern instead

설치

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

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

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

사용법

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

<div style="display:flex;flex-wrap:wrap;min-width:0;min-height:320px">
  <section style="flex:1.6 1 20rem;min-height:320px;position:relative;display:grid;place-items:center;text-align:center;overflow:hidden;padding:2rem">
    <mv-particles data-fill connect></mv-particles>
    <div style="position:relative">
      <p style="margin:0;font:700 clamp(1.6rem,4vw,2.6rem)/1.1 var(--mv-font-sans);letter-spacing:-.03em">Everything is connected</p>
      <p style="margin:.6rem auto 1.2rem;max-width:30rem;color:var(--mv-fg-muted)">A constellation that parts as your cursor passes through.</p>
      <a class="mv-button" href="#particles">Build my network</a>
    </div>
  </section>
  <section style="flex:1 1 14rem;min-height:240px;position:relative;display:grid;place-items:center;text-align:center;overflow:hidden;box-shadow:-1px 0 0 var(--mv-border);padding:1.5rem">
    <mv-particles data-fill interaction="attract" color="var(--mv-accent)" density="1.4"></mv-particles>
    <div style="position:relative">
      <strong style="display:block;font-size:1.1rem">Attracted sparks</strong>
      <span style="font-size:.85rem;color:var(--mv-fg-muted)">interaction="attract"</span>
    </div>
  </section>
</div>

API

Attributes

Name	유형	Default	Description
`count`	number		Fixed count (otherwise proportional to the area, max 500 / 220 with connect).
`density`	number	`1`	Multiplies the automatic count.
`interaction`	repel \| attract \| none	`repel`	Reaction to the cursor.
`radius`	number	`120`	Cursor influence radius (px).
`connect`	boolean		Links nearby particles (constellation), and the cursor.
`link-distance`	number	`120`	Max link distance (px).
`color`	CSS color	`var(--mv-particles-color)`	Particle color (tokens accepted, follows the theme).
`link-color`	CSS color	`var(--mv-particles-link)`	Link color.
`size`	number	`2`	Max particle radius (px).
`speed`	number	`1`	Drift speed.
`data-fill`	boolean		Fills the positioned parent; the cursor is then tracked on the parent.

CSS variables

Name	Default	Description
`--mv-particles-color`	`fg 75%`	Default particle color.
`--mv-particles-link`	`accent 70%`	Default link color.

Accessibility

Decorative: the canvas is aria-hidden and never takes pointer events, while content placed inside the element stays readable by assistive tech; with data-fill the whole element ignores the pointer and the parent section drives the interaction. The loop pauses off screen and in hidden tabs; every listener and observer is released on disconnect. Reduced motion (OS or [data-motion="reduce"]): a still image with no cursor reaction. Forced colors and print hide the canvas.