beta

Border Beam — `<mv-border-beam>`

Animated light that travels the border of any box: a constant-speed comet, conic highlights, a shifting gradient, gliding stars or an electric border.

Category	Effects
Type	CSS only (`<mv-border-beam>`)
Status	beta
Keywords	border, beam, shine, gradient-border, star-border, electric, conic, glow

When to use

A featured pricing plan, CTA card or new-feature box needs light traveling around its border
A primary button or card should get an animated gradient, star or electric outline
Several cards need offset beams to add a subtle sense of activity on a dark landing page

Avoid when

The element needs a soft halo behind it rather than an animated edge → use Glow instead
The border light should react to the cursor across a grid of cards → use Spotlight Card instead
Many boxes on the same screen would animate at once, diluting emphasis and adding motion noise

Install

node scripts/add.mjs border-beam --out ./src/marvelous

AI agent with the Marvelous UI MCP server: install_components({ slugs: ["border-beam"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).

Files copied (dependencies included): tokens/tokens.css, core/base.css, core/element.js, core/motion.js, core/observe.js, components/border-beam/border-beam.css, components/border-beam/border-beam.js.

Usage

Canonical markup — start from it and customize with attributes, data-* and CSS variables:

<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,18rem),1fr));gap:1.25rem;width:100%;max-width:44rem;margin:auto">
  <article class="mv-card">
    <header class="mv-card-header">
      <h3 class="mv-card-title">Pro plan</h3>
      <p class="mv-card-description">beam — a comet travels the border</p>
    </header>
    <div class="mv-card-content">
      <div class="mv-card-stat">$29<span style="font-size:.9rem;font-weight:500;color:var(--mv-fg-muted)"> / month</span></div>
      <p style="margin:.5rem 0 0;color:var(--mv-fg-muted)">Unlimited projects, 10 seats, priority support.</p>
    </div>
    <footer class="mv-card-footer"><button class="mv-button" style="width:100%">Upgrade to Pro</button></footer>
    <span class="mv-border-beam" aria-hidden="true"></span>
  </article>

  <article class="mv-card">
    <header class="mv-card-header">
      <h3 class="mv-card-title">New: PDF exports</h3>
      <p class="mv-card-description">shine — rotating conic highlights</p>
    </header>
    <div class="mv-card-content">
      <p style="margin:0;color:var(--mv-fg-muted)">Generate signed reports in one click, straight from your dashboards.</p>
    </div>
    <span class="mv-border-beam" data-variant="shine" aria-hidden="true"></span>
  </article>

  <article class="mv-card">
    <header class="mv-card-header">
      <h3 class="mv-card-title">Writing assistant</h3>
      <p class="mv-card-description">gradient — a shifting gradient border</p>
    </header>
    <div class="mv-card-content">
      <p style="margin:0;color:var(--mv-fg-muted)">Rephrase, summarize and translate your content without leaving the editor.</p>
    </div>
    <span class="mv-border-beam" data-variant="gradient" aria-hidden="true"></span>
  </article>

  <article class="mv-card">
    <header class="mv-card-header">
      <h3 class="mv-card-title">Turbo mode</h3>
      <p class="mv-card-description">electric — a crackling border (JS)</p>
    </header>
    <div class="mv-card-content">
      <p style="margin:0;color:var(--mv-fg-muted)">4× faster builds on dedicated infrastructure.</p>
    </div>
    <mv-border-beam data-variant="electric" style="--mv-border-beam-color-from:oklch(0.78 0.15 220)"></mv-border-beam>
  </article>
</div>

<div style="display:flex;flex-wrap:wrap;gap:1rem;justify-content:center;align-items:center;margin-top:1.75rem">
  <button class="mv-button" data-variant="outline" data-shape="pill" data-size="lg">
    Book a demo
    <span class="mv-border-beam" data-variant="star" aria-hidden="true"></span>
  </button>
  <button class="mv-button" data-variant="secondary" data-size="lg" style="--mv-border-beam-size:3rem;--mv-border-beam-duration:4s">
    Join the beta
    <span class="mv-border-beam" aria-hidden="true"></span>
  </button>
  <button class="mv-button" data-variant="outline" data-size="lg" style="--mv-border-beam-size:3rem;--mv-border-beam-duration:4s">
    View the changelog
    <span class="mv-border-beam" data-reverse aria-hidden="true" style="--mv-border-beam-color-from:oklch(0.75 0.17 160);--mv-border-beam-color-to:oklch(0.85 0.12 200)"></span>
  </button>
</div>

API

Attributes

Name	Type	Default	Description
`data-variant`	beam \| shine \| gradient \| star \| electric	`beam`	beam: a comet along the perimeter (offset-path, constant speed); shine: rotating conic highlights; gradient: a rotating gradient border, brighter on hover; star: two glows sliding along the top and bottom in opposite directions; electric: a crackling border (SVG filter, requires border-beam.js).
`data-reverse`	boolean		beam variant: reverse direction.

Methods

Name	Description
`ensureElectricFilter()`	JS export: injects the electric filter if you use the class on a `<span>` instead of the element.

Content structure

Name	Description
`<mv-border-beam>`	Optional element form (border-beam.js): adds the class and aria-hidden; required for electric (injects the shared turbulence filter, paused off-screen and with reduced motion).

CSS classes

Name	Description
`mv-border-beam`	Decorative layer to place as the last child of a positioned box (.mv-card, .mv-button…): `<span class="mv-border-beam" aria-hidden="true">`. Inherits the parent’s radius, masked into a ring.

CSS variables

Name	Default	Description
`--mv-border-beam-width`	`1.5px (2px for gradient/star/electric)`	Ring thickness.
`--mv-border-beam-size`	`5rem`	Comet length / star glow size.
`--mv-border-beam-duration`	`6s`	Duration of one lap.
`--mv-border-beam-delay`	`0s`	Start delay.
`--mv-border-beam-start`	`0`	Start position (0 to 1) along the perimeter, to offset several beams.
`--mv-border-beam-color-from / -via / -to`	`accent / pink / amber`	Light colors.
`--mv-border-beam-offset`	`18%`	Frozen comet position with reduced motion.
`--mv-border-beam-radius`	`var(--mv-radius-xl)`	Path radius when the browser can’t follow the box (offset-path: border-box).
`--mv-border-beam-inset`	`3px`	electric: stroke inset to leave room for the jitter.
`--mv-border-beam-z`	`3`	Layer z-index.

Accessibility

Purely decorative: aria-hidden, pointer-events: none. With reduced motion every variant freezes (the comet stays parked on the edge, the electric filter is paused).