Dot Matrix `<mv-dot-matrix>`

由方形圆点组成的 WebGL 网格：加载时它们伴着一道短促的火花从中心向外逐个点亮，然后每个点在各自的随机时刻重新随机亮度，形成平静的闪烁，少数强调色圆点呼吸得更亮，指针周围还会出现一片更活跃的区域。

工作原理

由方形圆点组成的 WebGL 网格：加载时它们伴着一道短促的火花从中心向外逐个点亮，然后每个点在各自的随机时刻重新随机亮度，形成平静的闪烁，少数强调色圆点呼吸得更亮，指针周围还会出现一片更活跃的区域。完全自包含（无需安装着色器运行时），离开屏幕时暂停，与页面共享 WebGL 上下文配额，减少动态效果时显示完全展开的静态网格。

分类	背景
类型	WebGL 元素（`<mv-dot-matrix>`）
状态	稳定版
Keywords	webgl, shader, dots, matrix, reveal, grid, flicker, hero

When to use

A hero or launch section should reveal a colorful dot grid from the center on load
A tech or data brand wants a calm flickering dot field that brightens around the pointer

Avoid when

A static or CSS-only dot texture is enough, e.g. behind docs or app screens → use Dot Pattern instead
A quiet dot texture should fade out behind a section title with no script at all → use Backdrop instead

安装

node scripts/add.mjs dot-matrix --out ./src/marvelous

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

用法

标准标记，可在此基础上通过属性、data-* 和 CSS 变量进行定制：

<mv-dot-matrix data-fill></mv-dot-matrix>
<div style="position:relative;display:grid;place-items:center;height:100%;min-height:320px;color:white;text-align:center;pointer-events:none">
  <div>
    <p style="margin:0;font:700 clamp(1.6rem,4vw,2.6rem)/1.1 var(--mv-font-sans);letter-spacing:-.03em;text-shadow:0 4px 24px rgb(0 0 0 / .45)">Every signal, one grid</p>
    <p style="margin:.5rem 0 0;opacity:.8;font-size:.9rem">&lt;mv-dot-matrix spacing="10"&gt;</p>
  </div>
</div>

API

Attributes

Name	类型	Default	Description
`colors`	CSS colors (3)	`var(--mv-accent), #38bdf8, #e879f9`	Dot palette: main tint, then the two accent colors (tokens accepted, re-read on theme change).
`dot-size`	number	`2.5`	Dot side length, in CSS pixels.
`spacing`	number	`10`	Grid pitch, in CSS pixels.
`reveal`	number	`1.6`	Duration of the reveal from the center (seconds per unit of distance, one unit being the element's height).
`flicker`	number	`1`	Flicker speed (0 = dots hold their level).
`accent`	number	`0.025`	Share of brighter accent dots (0 to 0.5).
`hover-radius`	number	`0.3`	Radius of the zone that wakes up around the pointer (fraction of the height).
`speed`	number	`1`	Time multiplier.
`paused`	boolean		Freezes the grid on the current frame (fully revealed if paused from the start).
`interactive`	boolean		Only pointer moves over the element itself count; by default the window is watched, so content on top does not block the hover zone.
`dpr`	number	`1.5`	Max pixel density (capped at 2).
`data-fill`	boolean		Fills the positioned parent (absolute, inset 0).

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. The loop stops off screen and in hidden tabs; reduced motion (OS or <html data-motion="reduce">) and paused show a still, fully revealed grid with no hover zone. Without WebGL2 a still CSS dot grid is shown; forced colors and print hide the canvas.