Beams `<mv-beams>`

单个 canvas 上的光束：拖着渐隐尾巴的彗星沿着汇聚到右上角的曲线疾驰，或者光线越落越快，在发光的地面上迸散成火花。

工作原理

单个 canvas 上的光束：拖着渐隐尾巴的彗星沿着汇聚到右上角的曲线疾驰，或者光线越落越快，在发光的地面上迸散成火花。颜色来自 CSS 变量并跟随主题；离开屏幕时循环暂停，减少动态效果时显示一帧没有迸散的静态画面。

分类	背景
类型	Web Component（`<mv-beams>`）
状态	稳定版
Keywords	safe-rewrite, beams, light, comet, collision, sparks, hero, canvas

When to use

A dark tech or AI hero needs streaks of light racing along fanned curves toward a focal point
A playful section where rays fall and burst into sparks on impact (collision variant)
Streaking light is wanted from one lightweight 2D canvas instead of a shader

Avoid when

The beam must visibly connect two specific elements, as in an integration diagram → use Animated Beam instead
Light should travel around the border of a single card or button → use Border Beam instead
Still rays behind a section are enough and nothing should move → use Backdrop instead

安装

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

使用 Marvelous UI MCP 服务器的 AI 智能体：install_components({ slugs: ["beams"], 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, components/beams/beams.css, components/beams/beams.js。

用法

标准标记，可在此基础上通过属性、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-beams data-fill></mv-beams>
    <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">Deploy at the speed of light</p>
      <p style="margin:.6rem auto 1.2rem;max-width:30rem;color:var(--mv-fg-muted)">One light canvas that rests whenever it leaves the screen.</p>
      <a class="mv-button" href="#beams">Start your project</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-beams variant="collision" data-fill></mv-beams>
    <div style="position:relative">
      <strong style="display:block;font-size:1.1rem">Collision</strong>
      <span style="font-size:.85rem;color:var(--mv-fg-muted)">Rays burst into sparks on the floor</span>
    </div>
  </section>
</div>

API

Attributes

Name	类型	Default	Description
`variant`	sweep \| collision	`sweep`	Comets along converging curves, or rays that fall and burst.
`count`	number	`16 (sweep) / 9 (collision)`	Number of beams (up to 40 curves or 30 rays).
`speed`	number	`1`	Speed multiplier.
`data-fill`	boolean		Fills the positioned parent (absolute, inset 0) and ignores the pointer.

Content structure

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

CSS variables

Name	Default	Description
`--mv-beams-from / -via / -to`	`accent hue −80° / accent / +50°`	Beam colors: the sweep gradient runs from the bottom-left to the top-right; rays fade from via to to.
`--mv-beams-line`	`fg 7%`	Resting curves (sweep).
`--mv-beams-glow`	`4px`	Halo around the comet heads (0 removes it).

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. The loop stops off screen and in hidden tabs. Reduced motion (OS or [data-motion="reduce"]): one still frame, beams mid-course, no bursts. Forced colors and print hide the canvas.