Waves `<mv-waves>`

单个 canvas 上的波浪线：一片透视视角下的等高线之海从朦胧的地平线涌来，越近越汹涌；或是几条由细丝构成的扭转丝带。

工作原理

单个 canvas 上的波浪线：一片透视视角下的等高线之海从朦胧的地平线涌来，越近越汹涌；或是几条由细丝构成的扭转丝带。启用 interactive 后，线条会在指针下方隆起柔和的涌浪，指针移动或按下的地方会荡开涟漪。颜色来自 CSS 变量并跟随主题；循环在离开屏幕时暂停，减少动态效果时显示静态画面。

分类	背景
类型	Web Component（`<mv-waves>`）
状态	稳定版
Keywords	safe-rewrite, waves, lines, ribbons, noise, perspective, ripple, interactive, hero, canvas

When to use

A SaaS or product hero needs a calm sea of moving lines behind the headline, in light or dark themes
Visitors should feel the page respond: the lines swell under the pointer and ripple where it moves or taps
Flowing lines or twisting ribbons are wanted from one 2D canvas, without a WebGL context

Avoid when

A still wave pattern is enough and nothing should move → use Backdrop instead

安装

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

使用 Marvelous UI MCP 服务器的 AI 智能体：install_components({ slugs: ["waves"], 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/pointer.js, components/waves/waves.js, components/waves/waves.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-waves data-fill interactive></mv-waves>
    <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">Ride the next wave</p>
      <p style="margin:.6rem auto 1.2rem;max-width:30rem;color:var(--mv-fg-muted)">Lines roll in from the horizon. Move your cursor to send ripples across them.</p>
      <a class="mv-button" href="#waves">Get started</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-waves data-fill variant="ribbons" interactive></mv-waves>
    <div style="position:relative">
      <strong style="display:block;font-size:1.1rem">Ribbons</strong>
      <span style="font-size:.85rem;color:var(--mv-fg-muted)">variant="ribbons"</span>
    </div>
  </section>
</div>

API

Attributes

Name	类型	Default	Description
`variant`	lines \| ribbons	`lines`	A sea of lines in perspective, or twisting ribbons made of strands.
`count`	number	`44 (lines) / 3 (ribbons)`	Number of lines on the sea (2 to 80) or of ribbons (1 to 8).
`colors`	list of CSS colors	`--mv-waves-1, -2, -3`	Comma-separated palette (tokens and var() accepted, follows the theme). Lines run through it from left to right, ribbon strands from one edge to the other.
`amplitude`	number	`1`	Swell height (0 flattens the lines).
`speed`	number	`1`	Speed multiplier for the flow and the ripples.
`interactive`	boolean		The lines rise in a soft swell under the pointer, moving it sends ripples and a press sends a stronger one (listens on the parent with data-fill).
`radius`	number	`220`	Pointer reach in px: how far a ripple travels before it dies out, and the size of the swell.
`data-fill`	boolean		Fills the positioned parent (absolute, inset 0) and lets the pointer through.

Content structure

Name	Description
`children`	Without data-fill, content placed inside the element sits above the waves.

CSS variables

Name	Default	Description
`--mv-waves-1 / -2 / -3`	`accent hue −40° / accent / +95°`	Default palette, darker in light theme and lighter in dark theme.
`--mv-waves-weight`	`1`	Line width multiplier.
`--mv-waves-haze`	`1`	Strength of the glow along the horizon (lines variant, 0 removes it).
`--mv-waves-mask`	`none`	Mask applied to the canvas, for example a fade on the sides.

Accessibility

Decorative: the canvas is aria-hidden and never takes pointer events, and content placed inside stays readable by assistive tech. With data-fill the whole element ignores the pointer; ripples come from pointer events on the parent and never block clicks. The loop stops off screen and in hidden tabs. Reduced motion (OS or [data-motion="reduce"]): one still frame, no swell and no ripples. Forced colors and print hide the canvas. Keep text readable over the lines: the far lines near the horizon are the faintest, so a centered headline sits well there.