Ripple Grid `<mv-ripple-grid>`

원근으로 본 바닥 위의 제도용 그리드를 얇은 물막 아래에 있는 것처럼 그리는 WebGL 배경입니다. 고리가 일정한 박자로 원점에서 퍼져 나가며 지나는 선을 휘게 하고, 강조 색으로 물들이고, 반짝임을 냅니다.

작동 방식

원근으로 본 바닥 위의 제도용 그리드를 얇은 물막 아래에 있는 것처럼 그리는 WebGL 배경입니다. 고리가 일정한 박자로 원점에서 퍼져 나가며 지나는 선을 휘게 하고, 강조 색으로 물들이고, 반짝임을 냅니다. 포인터는 돋보기 렌즈를 지니고, 클릭하면 강한 물결이 일며, 움직이는 포인터는 부드러운 자취를 남깁니다. 색상은 테마 토큰에서 가져오므로 라이트와 다크 테마 모두에서 작동합니다.

카테고리	배경
유형	WebGL 요소 (`<mv-ripple-grid>`)
상태	안정
함께 설치되는 항목	shader
Keywords	safe-rewrite, webgl, shader, grid, ripple, water, perspective, interactive, hero

When to use

A developer tool, API or SaaS hero wants a technical grid with a calm pulse behind the headline, in light or dark themes
Clicks and pointer moves should send ripples across the backdrop as playful feedback
A ripple must be triggered from code, e.g. on a successful submit or a milestone

Avoid when

A static or CSS-only grid is enough, or a retro scrolling floor is wanted → use Grid Pattern instead
Flowing wave lines rolling in from a horizon fit better than a ruled grid → use Waves instead
A rotating sweep with blips suits a monitoring theme better → use Radar instead

설치

node scripts/add.mjs ripple-grid --out ./src/marvelous

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

복사되는 파일(의존성 포함): tokens/tokens.css, core/base.css, core/canvas.js, core/dom.js, core/element.js, core/i18n.js, core/motion.js, core/observe.js, core/webgl.js, components/shader/shader.js, components/shader/shader.css, components/ripple-grid/ripple-grid.js, components/ripple-grid/ripple-grid.css.

사용법

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

<div style="display:flex;flex-wrap:wrap;min-height:320px">
  <section style="flex:1.6 1 22rem;position:relative;display:grid;place-items:center;text-align:center;overflow:hidden;padding:2rem 1.5rem">
    <mv-ripple-grid data-fill></mv-ripple-grid>
    <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">Ship on a steady beat</p>
      <p style="margin:.6rem auto 1.2rem;max-width:30rem;color:var(--mv-fg-muted)">Rings roll across the grid. Click anywhere to drop your own.</p>
      <a class="mv-button" href="#ripple-grid">Start building</a>
    </div>
  </section>
  <section style="flex:1 1 14rem;position:relative;display:grid;place-items:center;text-align:center;overflow:hidden;border-left:1px solid var(--mv-border);min-height:220px;padding:1.5rem">
    <mv-ripple-grid data-fill perspective="0" cells="9" origin="0.2 0.3" interval="3"></mv-ripple-grid>
    <div style="position:relative">
      <strong style="display:block;font-size:1.1rem">Flat grid</strong>
      <span style="font-size:.85rem;color:var(--mv-fg-muted)">perspective="0" origin="0.2 0.3"</span>
    </div>
  </section>
</div>

API

Attributes

Name	유형	Default	Description
`color`	CSS color	`var(--mv-accent)`	Accent of the rings, glints and pointer lens (tokens accepted, read again on theme change).
`background`	CSS color	`var(--mv-bg)`	Paper color under the grid (tokens accepted).
`line-color`	CSS color	`var(--mv-fg)`	Ink of the grid lines, drawn at low opacity over the paper (tokens accepted).
`cells`	number	`10`	Number of cells along the height, at the middle of the frame.
`major`	number	`4`	A stronger line, with crosses where two meet, every N cells (0 or 1 removes them).
`amplitude`	number	`1`	How much the rings bend the lines and how bright their glint is (0 keeps only the tint).
`line`	number	`1`	Line thickness multiplier.
`perspective`	number	`0.5`	Tilt of the floor toward the back (0 = flat grid seen from above, up to 0.9).
`interval`	number	`2.4`	Seconds between two rings leaving the origin (0.4 minimum).
`origin`	x y	`0.5 0.42`	Where the beat starts, in 0..1 element coordinates (y pointing up).
`trail`	number	`1`	Strength of the soft wake left by a moving mouse or pen, 0 to 2 (0 turns it off; clicks still drop ripples).
`speed`	number	`1`	Time multiplier.
`paused`	boolean		Freezes the animation on the current frame.
`interactive`	boolean		Lens and ripples follow the pointer only over the element itself (otherwise anywhere inside its area, even over content placed above it).
`dpr`	number	`1.5`	Max pixel density (capped at 2).
`data-fill`	boolean		Fills the positioned parent (absolute, inset 0).

Methods

Name	Description
`ripple(x, y, strength = 1)`	Drops a ripple at (x, y), in 0..1 element coordinates (y pointing up); strength from 0 to 2. Ignored while paused or under reduced motion.

Events

Name	Description
`mv-error`	Inherited from `<mv-shader>`: the GLSL failed to compile. The element shows its still fallback grid.

Content structure

Name	Description
`children`	Content placed inside the element sits above the grid.

Accessibility

Decorative: the canvas is aria-hidden and never takes pointer events, and ripples come from window pointer events, so clicks on content above the grid still work. The loop stops off screen and in hidden tabs, and no WebGL context is created until the element nears the viewport. Reduced motion (OS or <html data-motion="reduce">) and paused keep a still frame with a few rings, and no ripple is emitted. Without WebGL2 a still CSS grid with rings is shown; forced colors and print hide the canvas. Rings pass behind the content: keep headline text in the theme foreground, which the faint grid leaves readable.