Border Beam

Install: npm install border-beam@1.4.1

When to use

Highlight an input, button or card perimeter without changing its native semantics.

Key native props

Interaction and state checks

Try all five shapes and eight palettes, toggle active by keyboard, and verify halo clipping inside containers. The wrapper does not create the child's label, focus or disabled state.

Integration boundaries

CSS/SVG decoration only; it does not submit forms or report real processing. Supply reduced-motion behavior and use the native import, not JGuang's similarly named component.

Example files and host setup

Copy the component file and shared.tsx from examples in the source panel, keeping their relative locations; do not copy only the upstream implementation. Install the pinned npm package and use its own export in a browser component. Examples need no Tailwind or competing theme provider, read host html language/theme and provide reduced-motion/graphics fallbacks. Native implementation references are for reading; import via npm rather than copying an incomplete engine. Showcase labels are not new native props. Upstream detailed prose remains English; no full-translation claim is made.

Runnable usage

"use client";
import { useState } from "react";
import { BorderBeam, type BorderBeamColorVariant, type BorderBeamSize } from "border-beam";
import { DemoFrame, GraphicsGuard, control, demoTheme, panel, t } from "./shared";
export default function Example({ variant = "Default" }: { variant?: string }) {
  const sizes: Record<string, BorderBeamSize> = { Default: "md", Small: "sm", Line: "line", "Pulse outside": "pulse-outside", "Pulse inner": "pulse-inner", Inactive: "md" };
  const [size, setSize] = useState<BorderBeamSize>(sizes[variant] ?? "md");
  const [color, setColor] = useState<BorderBeamColorVariant>("ocean"), [active, setActive] = useState(variant !== "Inactive");
  return <DemoFrame status={`size=${size}, colorVariant=${color}, active=${active}`} controls={<>
    <label>{t("Shape", "形态")} <select style={control} aria-label={t("Beam shape", "光束形态")} value={size} onChange={e => setSize(e.target.value as BorderBeamSize)}>{Object.entries(sizes).filter(([key]) => key !== "Inactive").map(([key, value]) => <option key={key} value={value}>{value}</option>)}</select></label>
    <label>{t("Palette", "配色")} <select style={control} aria-label={t("Beam palette", "光束配色")} value={color} onChange={e => setColor(e.target.value as BorderBeamColorVariant)}>{["colorful", "mono", "ocean", "sunset", "forest", "candy", "ice", "gold"].map(value => <option key={value}>{value}</option>)}</select></label>
    <button type="button" style={control} aria-pressed={active} onClick={() => setActive(!active)}>{active ? t("Deactivate", "关闭特效") : t("Activate", "开启特效")}</button>
  </>}><GraphicsGuard kind="svg"><BorderBeam size={size} colorVariant={color} theme={demoTheme()} active={active} style={{ width: "100%", maxWidth: 320 }}><div style={panel}>{t("A native border effect around your content", "环绕内容的原生边框特效")}</div></BorderBeam></GraphicsGuard></DemoFrame>;
}

Preview states

Default, Small, Line, Pulse outside, Pulse inner, Inactive

Demo state and mock data do not provide a backend service. Inspect the component props before wiring real data.

border-beam

Animated border beam effect for React. 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

Quick start

import { BorderBeam } from 'border-beam';

function App() {
  return (
    <BorderBeam>
      <div style={{ padding: 32, borderRadius: 16, background: '#1d1d1d' }}>
        Your content here
      </div>
    </BorderBeam>
  );
}

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

Types

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

Rotate (traveling beam)

<BorderBeam size="md">  {/* Full border glow (default) */}
  <Card />
</BorderBeam>

<BorderBeam size="sm">  {/* Compact glow for small elements */}
  <IconButton />
</BorderBeam>

<BorderBeam size="line">  {/* Bottom-only traveling glow */}
  <SearchBar />
</BorderBeam>

Pulse (breathing glow, no rotation)

<BorderBeam size="pulse-inner">    {/* Contained breathing border glow */}
  <Card />
</BorderBeam>

<BorderBeam size="pulse-outside">  {/* Outward-blooming halo around the element */}
  <Card />
</BorderBeam>

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 colorVariant="colorful" />  {/* Rainbow spectrum (default) */}
<BorderBeam colorVariant="mono" />      {/* Grayscale */}
<BorderBeam colorVariant="ocean" />     {/* Blue-purple tones */}
<BorderBeam colorVariant="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}>  {/* 70% intensity */}
  <Card />
</BorderBeam>

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

Play / pause

Toggle the animation on and off with smooth fade transitions:

const [active, setActive] = useState(true);

<BorderBeam active={active} onDeactivate={() => console.log('faded out')}>
  <Card />
</BorderBeam>

Props

All standard HTMLDivElement attributes are also forwarded to the wrapper.

How it works

BorderBeam 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/
├── src/
│   ├── index.ts          # Public exports
│   ├── BorderBeam.tsx     # React component
│   ├── types.ts           # TypeScript type definitions
│   ├── styles.ts          # CSS generation engine
│   └── pulseDriver.ts     # Shared rAF loop driving the pulse breathing
├── demo/                  # Vite + React demo site
├── dist/                  # Built output (ESM + CJS + types)
├── package.json
├── LICENSE
└── README.md

Requirements

• React 18+
• 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

Source-backed parameter reference

Implementation signatures and types are generated from the pinned local source. Optional props, native inherited types, union branches and never exclusions are preserved. A forwardRef implementation's ref is a React reference, not an additional business prop.

BorderBeam({
      children,
      size = 'md',
      colorVariant = 'colorful',
      theme = 'dark',
      staticColors = false,
      duration,
      active = true,
      borderRadius: customBorderRadius,
      brightness: brightnessProp,
      saturation,
      hueRange = 30,
      glowSize = 1,
      strength = 1,
      className,
      style,
      css: extraCss,
      onActivate,
      onDeactivate,
      onAnimationEnd: consumerOnAnimationEnd,
      ...props
    }: BorderBeamProps, ref: ForwardedRef<HTMLDivElement>)

export type BorderBeamSize = 'sm' | 'md' | 'line' | 'pulse-outside' | 'pulse-inner';

export type BorderBeamTheme = 'dark' | 'light' | 'auto';

export type BorderBeamColorVariant =
  | 'colorful'
  | 'mono'
  | 'ocean'
  | 'sunset'
  | 'forest'
  | 'candy'
  | 'ice'
  | 'gold';

export interface BorderBeamProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
  /** Content to wrap with the border beam effect */
  children: ReactNode;

  /**
   * Size/type preset
   * Rotate family: 'sm' (compact), 'md' (full border, default), 'line' (bottom traveling).
   * Pulse family: 'pulse-outside' (outward bloom), 'pulse-inner' (contained breathe).
   * @default 'md'
   */
  size?: BorderBeamSize;

  /**
   * Color variant for the beam effect
   * - 'colorful': Full rainbow spectrum (default)
   * - 'mono': Monochromatic grayscale
   * - 'ocean': Blue and purple tones
   * - 'sunset': Warm orange, yellow, and red tones
   * @default 'colorful'
   */
  colorVariant?: BorderBeamColorVariant;

  /**
   * Theme mode - adapts beam/glow colors for dark or light backgrounds
   * 'auto' detects system preference via prefers-color-scheme
   * @default 'dark'
   */
  theme?: BorderBeamTheme;

  /**
   * Disable the hue-shift animation for static colors (e.g., monochrome)
   * @default false
   */
  staticColors?: boolean;

  /**
   * Rotation/travel duration in seconds
   * @default 1.96 for border, 2.4 for line
   */
  duration?: number;

  /**
   * Whether the animation is active
   * @default true
   */
  active?: boolean;

  /**
   * Custom border radius in pixels. When omitted, the component
   * auto-detects the border-radius of the first child element.
   * Falls back to the size preset default if detection fails.
   */
  borderRadius?: number;

  /**
   * Brightness multiplier for the glow effect.
   * Falls back to the type's preset default (1.3 for most types).
   * @default 1.3
   */
  brightness?: number;

  /**
   * Saturation multiplier for the glow effect
   * @default 1.2 for dark, varies for light
   */
  saturation?: number;

  /**
   * Multiplies the blur radius of every glow layer, so the halo reads
   * tighter (< 1) or wider and softer (> 1). Each layer keeps its own
   * tuned proportion — the core stays tighter than the bloom — because
   * this scales the presets rather than replacing them.
   * @default 1
   */
  glowSize?: number;

  /**
   * Hue rotation range in degrees for the hue-shift animation
   * @default 30
   */
  hueRange?: number;

  /**
   * Overall strength/opacity of the effect (0-1).
   * Only affects the beam, glow, and bloom layers -- not the children.
   * @default 1
   */
  strength?: number;

  /**
   * Additional class name for the container
   */
  className?: string;

  /**
   * Additional inline styles for the container
   */
  style?: CSSProperties;

  /**
   * Extra CSS appended after the beam's own generated stylesheet, so it can
   * override or add layers and keyframes. Write `{id}` wherever the
   * instance id belongs — the root is `[data-beam="{id}"]`, its layers are
   * the `::before` / `::after` pseudo-elements and `[data-beam-bloom]`, and
   * keyframes are named `*-{id}` — and it is substituted per instance.
   */
  css?: string;

  /**
   * Callback when fade-in animation completes
   */
  onActivate?: () => void;

  /**
   * Callback when fade-out animation completes
   */
  onDeactivate?: () => void;
}

Destructuring defaults in source

Only defaults written directly in parameter/props destructuring are listed. Conditional expressions, runtime theme and computed values require source inspection; this is not an exhaustive behavior-default list.

// BorderBeam
size = 'md'

// BorderBeam
colorVariant = 'colorful'

// BorderBeam
theme = 'dark'

// BorderBeam
staticColors = false

// BorderBeam
active = true

// BorderBeam
hueRange = 30

// BorderBeam
glowSize = 1

// BorderBeam
strength = 1

Native and external types

External types remain defined by React or native dependencies, not manually expanded into guessed props. The installed version's TypeScript definitions are authoritative.

HTMLDivElement
Omit<HTMLAttributes<HTMLDivElement>, 'children'>
HTMLAttributes<HTMLDivElement>
ReactNode
CSSProperties
ForwardedRef<HTMLDivElement>