BorderBeam

Basic Usage

Pulse Family

The pulse family does not rotate — the glow breathes on a shared ~30fps rAF loop. pulse-outside renders its halo behind the content layer and blooms outward, so it needs an opaque child with its own 1px border.

Composition Examples

Color and Theme

Four palettes; mono automatically disables the hue-shift animation. theme tunes the beam for dark or light backgrounds, and auto follows the system prefers-color-scheme.

<template>
  <TxBorderBeam color-variant="ocean" theme="light">
    <div class="card">ocean · light</div>
  </TxBorderBeam>
  <TxBorderBeam color-variant="sunset" :strength="0.7">
    <div class="card">sunset · 70%</div>
  </TxBorderBeam>
</template>

Custom Tempo

duration sets one travel loop or breathe cycle in seconds; hueRange bounds the hue drift and staticColors freezes it entirely.

<template>
  <TxBorderBeam :duration="4" :hue-range="60">
    <div class="card">slow · wide hue swing</div>
  </TxBorderBeam>
  <TxBorderBeam static-colors>
    <div class="card">frozen palette</div>
  </TxBorderBeam>
</template>

Interaction Contract

• The component wraps its slot content and overlays the beam layers; every effect layer is pointer-events: none and never blocks slot interaction.
• Without borderRadius, the border-top-left-radius of the first slot element is auto-detected; detection failure falls back to the size preset default.
• Toggling active runs a fade transition and emits activate / deactivate when the fade finishes.
• Animations pause automatically while the element is offscreen (256px margin, data-paused) without firing activate/deactivate.
• Each instance injects its own <style> scoped by the instance id (data-beam).
• The pulse family disables its breathing driver under prefers-reduced-motion: reduce.

API

Props

Slots

Events

Exposed Methods

No public instance methods.

CSS Variables

Best Practices

• Give the slot content its own background, with a corner radius matching the detected/explicit borderRadius, so the beam hugs the content edge.
• pulse-outside requires an opaque child with its own 1px border, plus surrounding layout room (overflow: visible) for the halo to spill.
• With several instances on one screen, lower strength or slow duration; this is a high-attention effect — one per view section is enough.
• Use theme="light" or "auto" on light pages; the dark tuning lacks contrast on light backgrounds.
• Beam layers never hit-test; slot content owns its own focus styling.

Review Notes

• Manually verified against index.ts, TxBorderBeam.vue, types.ts and border-beam.test.ts under packages/tuffex/packages/components/src/border-beam/.
• The CSS engine styles.ts and the pulse driver pulse-driver.ts are verbatim ports of upstream border-beam (MIT © Jakub Antalik) with strict-TS index hardening only.
• Events are activate / deactivate, mirroring the upstream React onActivate / onDeactivate callbacks.

Source

• Component source: packages/tuffex/packages/components/src/border-beam/src/TxBorderBeam.vue.
• Types: packages/tuffex/packages/components/src/border-beam/src/types.ts.
• Upstream: Jakubantalik/Libraries · border-beam (MIT).
• Coverage: packages/tuffex/packages/components/src/border-beam/__tests__/border-beam.test.ts verifies slot rendering, per-instance style injection, the active lifecycle with the deactivate event, and strength clamping.