border-beam-vue-port

Animated border beam effect for Vue 3. A lightweight component that adds a traveling or breathing glow animation around any element — cards, buttons, inputs, or search bars.

Install

npm install border-beam-vue-port

Quick start

BorderBeam works both as an installable plugin and as a directly-imported component.

As a plugin (registers a global <BorderBeam>):

// main.ts
import { createApp } from 'vue';
import { BorderBeam } from 'border-beam-vue-port';
import App from './App.vue';

createApp(App).use(BorderBeam).mount('#app');

Or imported directly:

<script setup lang="ts">
import { BorderBeam } from 'border-beam-vue-port';
</script>

<template>
  <BorderBeam>
    <div style="padding: 32px; border-radius: 16px; background: #1d1d1d">
      Your content here
    </div>
  </BorderBeam>
</template>

The component wraps the default slot and overlays the animated beam effect. It auto-detects the border-radius of the first child element.

In templates, props use kebab-case (color-variant, border-radius, static-colors, …). The camelCase names from the type definitions also work.

Types

Built-in presets control the glow style and motion. They fall into two families:

Rotate (traveling beam)

<BorderBeam size="md"><Card /></BorderBeam>     <!-- Full border glow (default) -->
<BorderBeam size="sm"><IconButton /></BorderBeam> <!-- Compact glow for small elements -->
<BorderBeam size="line"><SearchBar /></BorderBeam> <!-- Bottom-only traveling glow -->

Pulse (breathing glow, no rotation)

<BorderBeam size="pulse-inner"><Card /></BorderBeam>   <!-- Contained breathing border glow -->
<BorderBeam size="pulse-outside"><Card /></BorderBeam> <!-- Outward-blooming halo around the element -->

Both pulse types support all color variants, strength, theme, and the breathe speed via duration (defaults to 2.3).

pulse-outside requires an opaque wrapped child. The colorful core and halo render behind your content (z-index: -1) and bloom outward, so only the part that spills beyond the element shows. If your child is transparent, the inner glow will show through. The wrapper uses overflow: visible, so make sure the surrounding layout has room (or overflow: visible) for the halo to spill.

pulse-outside relies on the wrapped element's own 1px border as the idle hairline. It does not paint its own hairline by default, so the colored stroke rides directly on top of your element's existing edge instead of doubling it. If your child has no border, add a subtle 1px border (or box-shadow: inset 0 0 0 1px) so the edge stays defined while the beam is faded out.

Color variants

Four color palettes are available:

<BorderBeam color-variant="colorful" />  <!-- Rainbow spectrum (default) -->
<BorderBeam color-variant="mono" />      <!-- Grayscale -->
<BorderBeam color-variant="ocean" />     <!-- Blue-purple tones -->
<BorderBeam color-variant="sunset" />    <!-- Orange-yellow-red tones -->

All variants except mono animate through a hue-shift cycle.

Theme

Adapts beam colors for dark or light backgrounds:

<BorderBeam theme="dark" />   <!-- Dark background (default) -->
<BorderBeam theme="light" />  <!-- Light background -->
<BorderBeam theme="auto" />   <!-- Detects system preference -->

Strength

Control the overall intensity of the effect without affecting the wrapped content:

<BorderBeam :strength="0.7"><Card /></BorderBeam>  <!-- 70% intensity -->

strength accepts a value from 0 (invisible) to 1 (full intensity, default).

Play / pause

Toggle the animation on and off with smooth fade transitions, and listen for the fade-in / fade-out completion events:

<script setup lang="ts">
import { ref } from 'vue';
import { BorderBeam } from 'border-beam-vue-port';

const active = ref(true);
</script>

<template>
  <BorderBeam :active="active" @deactivate="() => console.log('faded out')">
    <Card />
  </BorderBeam>
</template>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | size | 'sm' \| 'md' \| 'line' \| 'pulse-outside' \| 'pulse-inner' | 'md' | Size/type preset | | colorVariant | 'colorful' \| 'mono' \| 'ocean' \| 'sunset' | 'colorful' | Color palette | | theme | 'dark' \| 'light' \| 'auto' | 'dark' | Background adaptation | | strength | number | 1 | Effect opacity (0–1), only affects the beam layers | | duration | number | 1.96 / 3.1 / 2.3 | Animation cycle duration in seconds (rotate / line / pulse) | | active | boolean | true | Whether the animation is playing | | borderRadius | number | auto-detected | Custom border radius in px | | brightness | number | per-type (1.3) | Glow brightness multiplier; falls back to the type's preset default | | saturation | number | 1.2 | Glow saturation multiplier | | hueRange | number | 30 | Hue rotation range in degrees | | staticColors | boolean | false | Disable hue-shift animation |

Slots

| Slot | Description | |------|-------------| | default | Content to wrap with the border beam effect |

Events

| Event | Description | |-------|-------------| | activate | Emitted when the fade-in animation completes | | deactivate | Emitted when the fade-out animation completes |

Standard native attributes — class, style, data-*, and listeners such as @animationend — fall through to the wrapper element automatically.

How it works

BorderBeam injects a per-instance <style> element and renders a wrapper <div> with:

• ::after — the beam stroke (rotate: conic gradient masked to the border; pulse: the colored perimeter ring / hairline)
• ::before — inner glow layer (pulse-outside pushes this outward behind the content)
• [data-beam-bloom] — outer bloom/glow child div

All effect layers are absolutely positioned and use pointer-events: none, so they never interfere with your content. The rotate and line types animate via CSS @property keyframes for smooth GPU-accelerated transitions; because the keyframes also declare explicit 0% / 50% / 100% stops, browsers without @property support degrade gracefully (stepped instead of interpolated motion) rather than breaking. The pulse types drive their slow breathing from a single shared, frame-rate-capped (~30fps) requestAnimationFrame loop that writes plain CSS custom properties — so the breathing works even without @property support, repaints less often, and automatically pauses when the instance is inactive, offscreen, or the user prefers reduced motion. The pulse types also isolate their stacking context, cap blur radii, and hint will-change on the animated layers for performance.

Project structure

border-beam-vue/
├── src/
│   ├── index.ts          # Public exports + plugin install
│   ├── BorderBeam.vue     # Vue 3 component
│   ├── types.ts           # TypeScript type definitions
│   ├── styles.ts          # CSS generation engine (framework-agnostic)
│   └── pulseDriver.ts     # Shared rAF loop driving the pulse breathing
├── demo/                  # Vite + Vue 3 demo / playground
├── dist/                  # Built output (ESM + CJS + types)
├── package.json
├── LICENSE
└── README.md

Requirements

• Vue 3.5+
• Modern browser with CSS @property support (Chrome 85+, Safari 15.4+, Firefox 128+)

Accessibility

The effect layers are purely decorative and use pointer-events: none. They do not affect keyboard navigation or screen readers. The pulse types ship a built-in prefers-reduced-motion: reduce block that disables their animations; the rotate types respect prefers-reduced-motion when implemented by the consumer.

License

MIT