border-beam-react

What this skill does

# border-beam-react

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

`border-beam` is a lightweight React component that renders an animated traveling glow/beam effect around any element — cards, buttons, inputs, search bars, or any container. It uses CSS `@property` for GPU-accelerated animations with no runtime animation libraries required.

## Installation

```bash
npm install border-beam
```

**Requirements:**
- React 18+
- Modern browser: Chrome 85+, Safari 15.4+, Firefox 128+

## Basic Usage

```tsx
import { BorderBeam } from 'border-beam';

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

`BorderBeam` wraps your content and auto-detects the `border-radius` of the first child element. All effect layers use `pointer-events: none` so they never block interaction.

## Size Presets

```tsx
// Full border glow (default) — for cards, panels
<BorderBeam size="md">
  <Card />
</BorderBeam>

// Compact glow — for small elements like icon buttons
<BorderBeam size="sm">
  <IconButton />
</BorderBeam>

// Bottom-only traveling glow — ideal for search bars, inputs
<BorderBeam size="line">
  <SearchBar />
</BorderBeam>
```

## Color Variants

```tsx
<BorderBeam colorVariant="colorful" /> {/* Rainbow spectrum (default), animates hue */}
<BorderBeam colorVariant="mono" />     {/* Grayscale, no hue animation */}
<BorderBeam colorVariant="ocean" />    {/* Blue-purple tones */}
<BorderBeam colorVariant="sunset" />   {/* Orange-yellow-red tones */}
```

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

## Theme (Dark / Light / Auto)

```tsx
<BorderBeam theme="dark" />  {/* Default — for dark backgrounds */}
<BorderBeam theme="light" /> {/* For light backgrounds */}
<BorderBeam theme="auto" />  {/* Detects system prefers-color-scheme */}
```

## Controlling Intensity

```tsx
// strength: 0 (invisible) to 1 (full, default) — only affects beam layers
<BorderBeam strength={0.6}>
  <Card />
</BorderBeam>

// brightness and saturation multipliers
<BorderBeam brightness={1.5} saturation={1.4}>
  <Card />
</BorderBeam>
```

## Play / Pause with Callbacks

```tsx
import { useState } from 'react';
import { BorderBeam } from 'border-beam';

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

  return (
    <>
      <BorderBeam
        active={active}
        onActivate={() => console.log('Beam faded in')}
        onDeactivate={() => console.log('Beam faded out')}
      >
        <div style={{ padding: 32, borderRadius: 16, background: '#111' }}>
          Hover-activated beam
        </div>
      </BorderBeam>
      <button onClick={() => setActive(a => !a)}>Toggle Beam</button>
    </>
  );
}
```

## Custom Duration and Hue Range

```tsx
<BorderBeam
  duration={3.5}      // Animation cycle in seconds (default: 1.96 for md, 2.4 for line)
  hueRange={60}       // Hue rotation range in degrees (default: 30)
  staticColors={true} // Disable hue-shift entirely
>
  <Card />
</BorderBeam>
```

## Custom Border Radius

If auto-detection doesn't work (e.g., the radius is set via a CSS class), override it:

```tsx
<BorderBeam borderRadius={24}>
  <div className="my-card">Content</div>
</BorderBeam>
```

## Forwarded HTML Attributes

The wrapper `<div>` forwards all standard `HTMLDivElement` attributes:

```tsx
<BorderBeam
  className="my-wrapper"
  style={{ display: 'inline-block' }}
  data-testid="beam-card"
>
  <Card />
</BorderBeam>
```

## Common Patterns

### Hover-activated beam

```tsx
import { useState } from 'react';
import { BorderBeam } from 'border-beam';

function HoverCard() {
  const [hovered, setHovered] = useState(false);

  return (
    <BorderBeam active={hovered} strength={0.85} colorVariant="ocean">
      <div
        onMouseEnter={() => setHovered(true)}
        onMouseLeave={() => setHovered(false)}
        style={{ padding: 24, borderRadius: 12, background: '#0f0f0f' }}
      >
        Hover me
      </div>
    </BorderBeam>
  );
}
```

### Search bar with line beam

```tsx
import { BorderBeam } from 'border-beam';

function SearchInput() {
  return (
    <BorderBeam size="line" colorVariant="sunset" theme="dark">
      <input
        type="text"
        placeholder="Search..."
        style={{
          padding: '12px 16px',
          borderRadius: 8,
          background: '#1a1a1a',
          border: '1px solid #333',
          color: '#fff',
          width: 320,
        }}
      />
    </BorderBeam>
  );
}
```

### Light theme card

```tsx
import { BorderBeam } from 'border-beam';

function LightCard() {
  return (
    <BorderBeam theme="light" colorVariant="colorful" strength={0.8}>
      <div style={{ padding: 32, borderRadius: 16, background: '#f5f5f5' }}>
        Light mode card
      </div>
    </BorderBeam>
  );
}
```

### Reduced motion accessibility

The component itself does not automatically respond to `prefers-reduced-motion`. Handle it in the consumer:

```tsx
import { useReducedMotion } from 'framer-motion'; // or your own hook
import { BorderBeam } from 'border-beam';

function AccessibleCard() {
  const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

  return (
    <BorderBeam active={!reduceMotion}>
      <Card />
    </BorderBeam>
  );
}
```

## Full Props Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Content to wrap |
| `size` | `'sm' \| 'md' \| 'line'` | `'md'` | Size/type preset |
| `colorVariant` | `'colorful' \| 'mono' \| 'ocean' \| 'sunset'` | `'colorful'` | Color palette |
| `theme` | `'dark' \| 'light' \| 'auto'` | `'dark'` | Background adaptation |
| `strength` | `number` | `1` | Beam opacity 0–1, does not affect children |
| `duration` | `number` | `1.96` / `2.4` | Animation cycle in seconds |
| `active` | `boolean` | `true` | Play/pause with fade transition |
| `borderRadius` | `number` | auto-detected | Override border radius in px |
| `brightness` | `number` | `1.3` | Glow brightness multiplier |
| `saturation` | `number` | `1.2` | Glow saturation multiplier |
| `hueRange` | `number` | `30` | Hue rotation range in degrees |
| `staticColors` | `boolean` | `false` | Disable hue-shift animation |
| `className` | `string` | — | Class on wrapper div |
| `style` | `CSSProperties` | — | Inline styles on wrapper div |
| `onActivate` | `() => void` | — | Called when fade-in completes |
| `onDeactivate` | `() => void` | — | Called when fade-out completes |

## How It Works

`BorderBeam` renders a wrapper `<div>` with three effect layers — all `pointer-events: none`, absolutely positioned, never affecting layout or interaction:

- **`::after`** — beam stroke (conic gradient masked to the border edge)
- **`::before`** — inner glow layer
- **`[data-beam-bloom]`** — outer bloom/glow child `<div>`

Animations use CSS `@property` for smooth, GPU-accelerated hue cycling.

## Troubleshooting

**Beam not visible:**
- Ensure the child element has a visible `background` and `border-radius`
- Check `strength` is not `0`
- Verify `active` is `true`

**Border radius not matching:**
- Pass `borderRadius` prop explicitly if the radius comes from a CSS class rather than inline style

**Effect covers content / blocks clicks:**
- All layers are `pointer-events: none` by default — if this is happening, check for CSS conflicts in your wrapper

**Animation not working in browser:**
- Requires CSS `@property` support: Chrome 85+, Safari 15.4+, Firefox 128+. Check [caniuse.com/@property](https://caniuse.com/css-at-property)

**SSR / Next.js:**
- The component uses DOM APIs for border-radius detection; wrap in a client component (`'use client'`) in Next.js App Router