BorderBeam | Tuff Docs

Usage

Rotating Types

size is sm, md, or line; line travels along the bottom edge only.

Loading demo...

Pulse Types

pulse-inner breathes inside the border. pulse-outside blooms outward from behind the content, so the child must be opaque with its own 1px border.

Loading demo...

Color and Theme

colorVariant picks one of four palettes. theme tunes the beam for dark or light backgrounds; auto follows the system.

<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>

Tempo

duration is one loop or breath in seconds. hueRange bounds the hue drift, and staticColors freezes it.

<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>

Best Practices

Give the slot content its own background and a corner radius that matches borderRadius.
Leave room around pulse-outside for the halo to spill (overflow: visible).
Use one beam per section; with several on screen, lower strength or slow duration.
Use theme="light" or "auto" on light pages; the default dark tuning lacks contrast there.

API Reference

Props

Prop	Type	Default	Description
`size`	`'sm' \| 'md' \| 'line' \| 'pulse-outside' \| 'pulse-inner'`	`'md'`	Type preset: rotating (`sm`, `md`, `line`) or pulse.
`colorVariant`	`'colorful' \| 'mono' \| 'ocean' \| 'sunset'`	`'colorful'`	Palette; `mono` also freezes the hue.
`theme`	`'dark' \| 'light' \| 'auto'`	`'dark'`	Tunes the beam for the background; `auto` follows the system.
`strength`	`number`	`1`	Beam-layer intensity (0–1); leaves the slot content untouched.
`duration`	`number`	`1.96` / `3.1` / `2.3`	Cycle length in seconds; defaults are for rotating, `line`, and pulse.
`active`	`boolean`	`true`	Plays the effect; toggling fades it in or out.
`borderRadius`	`number`	auto-detected	Beam corner radius in px.
`brightness`	`number`	per-type preset (`1.3`)	Glow brightness multiplier.
`saturation`	`number`	`1.2` (dark)	Glow saturation multiplier.
`hueRange`	`number`	`30`	Hue drift in degrees; capped at 13 for `line`.
`staticColors`	`boolean`	`false`	Turns off the hue animation.

Events

Event	Payload	Description
`activate`	-	Fires when the fade-in ends.
`deactivate`	-	Fires when the fade-out ends.

Slots

Slot	Props	Description
`default`	-	The wrapped content.

CSS Variables

Variable	Source	Description
`--beam-strength`	`strength`	Beam-layer opacity, clamped to 0–1.
`--pulse-glow-sx` / `--pulse-glow-sy`	internal measurement	Per-axis halo scale of `pulse-outside`, from the element size.
`--pulse-glow-boost`	optional consumer hook	Pulse glow gain; defaults to `1`.

Overview

Every effect layer is pointer-events: none and never blocks the slot; the slot content supplies its own focus styling.
Without borderRadius, the first slot element's border-top-left-radius is used, falling back to the type preset.
Offscreen (256px margin), the animation pauses without emitting activate / deactivate.
Under reduced motion, the pulse types stop breathing.

Technologies

Each instance injects its own <style> scoped by data-beam; the pulse types run on a shared ~30fps rAF loop.
Source: packages/tuffex/packages/components/src/border-beam/.

查看源码

packages/tuffex/packages/components/src/border-beam/index.ts