Grid Pattern `<mv-grid-pattern>`

纯 CSS 背景网格（实线或虚线、高亮单元格、径向渐隐），外加一个动画元素：闪烁、在光标下亮起并留下拖尾、点击时泛起涟漪的单元格，以及复古透视地面。

分类	背景
类型	Web Component（`<mv-grid-pattern>`）
状态	稳定版
Keywords	grid, pattern, flicker, retro, interactive, hero, canvas

When to use

A technical, blueprint-like backdrop is needed behind a hero, docs header or feature section
Cells should light up under the cursor with a trail and a click ripple to make a section feel alive
A synthwave or retro-gaming page wants a scrolling perspective floor
Specific cells must be highlighted to frame content, in pure CSS without JavaScript

Avoid when

A softer, less structured texture fits better than visible lines → use Dot Pattern instead

安装

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

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

用法

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

<div style="display:grid;grid-template-rows:320px 180px">
  <section style="position:relative;display:grid;place-items:center;text-align:center;overflow:hidden;padding:2rem">
    <mv-grid-pattern variant="interactive" data-fill></mv-grid-pattern>
    <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">Every cell responds to your cursor</p>
      <p style="margin:.6rem auto 1.2rem;max-width:32rem;color:var(--mv-fg-muted)">Hover to leave a trail, click to send a ripple.</p>
      <a class="mv-button" href="#grid-pattern">Explore the grid</a>
    </div>
  </section>
  <div style="display:grid;grid-template-columns:repeat(3,1fr);border-top:1px solid var(--mv-border)">
    <div class="mv-grid-pattern" data-variant="dashed" data-animate style="display:grid;place-items:center;--mv-grid-pattern-size:32px">
      <div class="mv-grid-pattern-cells" aria-hidden="true"><i style="--x:4;--y:1"></i><i style="--x:9;--y:2"></i><i style="--x:6;--y:3"></i><i style="--x:12;--y:1"></i><i style="--x:2;--y:3"></i><i style="--x:10;--y:4"></i></div>
      <strong style="font-size:.9rem">CSS · dashed</strong>
    </div>
    <div style="position:relative;display:grid;place-items:center;overflow:hidden;border-inline:1px solid var(--mv-border)">
      <mv-grid-pattern variant="flicker" data-fill></mv-grid-pattern>
      <strong style="position:relative;font-size:.9rem">Flicker</strong>
    </div>
    <div style="position:relative;display:grid;place-items:center;overflow:hidden">
      <mv-grid-pattern variant="retro" data-fill></mv-grid-pattern>
      <strong style="position:relative;font-size:.9rem;align-self:start;margin-top:1.4rem">Retro</strong>
    </div>
  </div>
</div>

API

Attributes

Name	类型	Default	Description
`variant`	flicker \| interactive \| retro		`<mv-grid-pattern>`: animated variant (no value: CSS grid).
`data-variant`	dashed		Dashed lines (class or element).
`data-fade`	radial \| top \| bottom \| edges \| none	`radial`	Fade mask.
`data-animate`	boolean		CSS class: highlighted cells pulse in a staggered way.
`data-fill`	boolean		Fills the positioned parent (absolute, inset 0).
`squares`	number		Default variant: N random cells that appear, then move around.
`size`	number	`4 (flicker) / 40 (interactive)`	Cell size in px.
`gap`	number	`6`	flicker: spacing between cells.
`color`	CSS color	`var(--mv-accent)`	Cell color (tokens accepted, follows the theme).
`max-opacity`	number	`0.4`	flicker: maximum opacity.
`chance`	number	`0.3`	flicker: probability of change per cell per second.
`trail`	number	`0.9`	interactive: trail duration in seconds.
`ambient`	"false"		interactive: disables cells that light up on their own.

CSS classes

Name	Description
`mv-grid-pattern`	CSS grid layer (no JS). data-fill fills a positioned parent.
`mv-grid-pattern-cells`	Container for highlighted cells; each child is placed via style="--x:3;--y:1".

CSS variables

Name	Default	Description
`--mv-grid-pattern-size`	`40px`	Grid step (56px for retro).
`--mv-grid-pattern-stroke`	`1px`	Line thickness.
`--mv-grid-pattern-color`	`fg 11%`	Line color.
`--mv-grid-pattern-cell`	`accent 18%`	Highlighted cell color (CSS).
`--mv-grid-pattern-dash`	`4px`	Dash length.
`--mv-grid-pattern-x / -y`	`0px`	Grid offset.
`--mv-grid-pattern-mask`		Custom mask (overrides data-fade).
`--mv-grid-pattern-angle`	`68deg`	retro: floor tilt.
`--mv-grid-pattern-speed`	`1.4s`	retro: time to travel one cell.

Accessibility

Purely decorative: the canvas and the generated cells are aria-hidden and the lines are pseudo-elements, so only content placed inside the element is exposed (mark a hand-written .mv-grid-pattern-cells, or an empty .mv-grid-pattern div, aria-hidden="true" yourself). pointer-events: none with data-fill (the interactive variant listens on the parent; a click only adds a visual ripple). Loops pause off screen and in hidden tabs, and every listener and observer is released on disconnect. Reduced motion (OS or [data-motion="reduce"]): grid and cells are static, highlighting is instant with no trail. Forced colors and print hide the pattern.